Index: trunk/SophyaLib/BaseTools/ppersist.cc
===================================================================
--- trunk/SophyaLib/BaseTools/ppersist.cc	(revision 2698)
+++ trunk/SophyaLib/BaseTools/ppersist.cc	(revision 2805)
@@ -21,5 +21,12 @@
 
 
-#define MAXTAGLEN 255
+
+/*!
+   \class SOPHYA::PIOPersist
+   \ingroup BaseTools
+   Handles (statically) the registration of PPF Sophya Persistence) handler classes. 
+   \sa PPersist
+*/
+
 
 //++
@@ -32,12 +39,4 @@
 //--
 
-//++
-// Links	See
-// PPersist
-// PInPersist
-// POutPersist
-//--
-
-
 MD5_CONTEXT PIOPersist::ctx;
 PIOPersist::ClassList * PIOPersist::ppclassList = NULL;   // $CHECK$ Reza 26/04/99
@@ -57,14 +56,12 @@
 }
 
-//++
+/*!
+  Register a new persistence handler (PPersist) class.
+  The classId is usually a hash of the class< name, and
+  ppclass_name is typeid(PPersistClass).name() .
+  This method is called only through the PPersistRegistrar template
+*/
 void
 PIOPersist::RegisterPPHandlerClass(uint_8 classId, string ppclass_name, ClassCreatorFunc f)
-//
-//	Register a new persistence handler (PPersist) class.
-//	The classId is usually a hash of the class< name, and
-//	ppclass_name is typeid(PPersistClass).name() .
-//	This method is called only through the PPersistRegistrar template
-//
-//--
 {
   if (ppclassList->size() && (ppclassList->find(classId) != ppclassList->end()) ) {
@@ -83,10 +80,10 @@
 }
 
-//++
+/*!
+  Register a new DataObj class corresponding to a PPersist classId
+  class_typename should be typeid(DataObject).name() 
+*/
 void
 PIOPersist::RegisterDataObjClass(uint_8 classId, string class_name)
-//	Register a new DataObj class corresponding to a PPersist classId
-//	class_typename should be typeid(DataObject).name() 
-//--
 {
   if (ppclassList->find(classId) == ppclassList->end() ) {
@@ -132,7 +129,7 @@
 }
 
+//! Returns the PPersist class creator function for the specified classId
 PIOPersist::ClassCreatorFunc
 PIOPersist::FindCreatorFunc(uint_8 classId)
-// Returns the PPersist class creator function for the specified classId
 {
   ClassList::iterator i = ppclassList->find(classId);
@@ -141,7 +138,7 @@
 }
 
+//! Returns the PPersist class name for the specified classId
 string 
 PIOPersist::getPPClassName(uint_8 classId)
-// Returns the PPersist class name for the specified classId
 {
   map<string, uint_8>::iterator i;
@@ -152,7 +149,7 @@
 }
 
+//! Returns the classId for the specified PPersist class type name
 uint_8
 PIOPersist::getPPClassId(string const & typ_name)
-// Returns the classId for the specified PPersist class type name
 {
   map<string, uint_8>::iterator i = ppclassNameList->find(typ_name);
@@ -162,7 +159,7 @@
 }
 
+//! Returns the classId for the specified PPersist class 
 uint_8
 PIOPersist::getPPClassId(PPersist const & ppo)
-// Returns the classId for the specified PPersist class 
 {
   string typ_name = typeid(ppo).name() ;
@@ -171,7 +168,7 @@
 
 
+//! Returns the PPersist class name for the specified classId
 string 
 PIOPersist::getDataObjClassName(uint_8 classId)
-// Returns the PPersist class name for the specified classId
 {
   map<string, uint_8>::iterator i;
@@ -182,7 +179,7 @@
 }
 
+//! Returns the classId for the specified PPersist class type name
 uint_8
 PIOPersist::getDataObjClassId(string const & typ_name)
-// Returns the classId for the specified PPersist class type name
 {
   map<string, uint_8>::iterator i = dobjclassNameList->find(typ_name);
@@ -192,7 +189,7 @@
 }
 
+//! Returns the classId for the specified PPersist class 
 uint_8
 PIOPersist::getDataObjClassId(AnyDataObj const & o)
-// Returns the classId for the specified PPersist class 
 {
   string typ_name = typeid(o).name() ;
@@ -200,4 +197,5 @@
 }
 
+//! \cond
 static inline void bswap8_hash(void* p)
 {
@@ -213,5 +211,5 @@
 }
 
-
+//! \endcond
 
 uint_8 PIOPersist::Hash(string const& typname) { 
@@ -238,6 +236,4 @@
 //	persistant :
 //	- Hériter de PPersist.
-//	- Définir un numéro d'identification de la classe, unique dans Peida
-//	- Implémenter "ClassId()"
 //	- Implémenter "WriteSelf" et "ReadSelf", qui doivent écrire toutes les variables
 //	  membres que l'on souhaite écrire, et les relire dans le même ordre.
@@ -253,17 +249,18 @@
 //--
 
-//++
-// Links	See
-// PInPersist
-// POutPersist
-// PIOPersist
-//--
-  
-//++
+/*!
+   \class SOPHYA::PPersist
+   \ingroup BaseTools
+   Ancestor (base) class for SOPHYA persistence (PPF) handlers. 
+   In order to have provide a PPF handler for an object :
+   - Inherit from PPersist
+   - Implement WriteSelf() and ReadSelf()
+
+   \sa PInPersist POutPersist PIOPersist
+*/
+
+//! Writes the object into a new PPF file named \b fn 
 void
 PPersist::Write(string const& fn) const
-//
-//	Ecrit l'objet dans un nouveau fichier ppersist "fn".
-//--
 {
   POutPersist of(fn);
@@ -271,12 +268,7 @@
 }
 
-//++
+//! Reads the object from a PInPersist stream created from file \b fn 
 void
 PPersist::Read(string const& fn) 
-//
-//	Relit l'objet dans le fichier ppersist "fn". Il faut connaître a priori
-//	le type de l'objet. Pour une relecture avec création automatique du bon
-//	objet, utiliser PPersistMgr::ReadObject.
-//--
 {
   PInPersist inf(fn);
@@ -285,10 +277,7 @@
 }
 
-//++
+//! Writes the object to the output PPF stream \b s
 void
 PPersist::Write(POutPersist& s) const
-//
-//	Ecrit l'objet dans le fichier PPersist.
-//--
 {
    s.PutPPObject(this);
@@ -296,5 +285,5 @@
 
 
-//++
+//! Reads the object from the input PPF stream \b s
 void
 PPersist::Read(PInPersist& s)
@@ -337,10 +326,7 @@
 }
 
-//++
+//! Writes a name tag (\b tag) and then the object to the output PPF stream \b s
 void
 PPersist::Write(POutPersist& s, string const& tag) const
-//
-//	Ecrit l'objet dans le fichier PPersist avec un tag 
-//--
 {
   s.WriteNameTag(tag);
@@ -348,10 +334,7 @@
 }
 
-//++
+//! Try to position at the name tag \b tag and then reads the object from the input stream \b s
 void
 PPersist::ReadAtTag(PInPersist& s, string const& tag)
-//
-//	Lit l'objet à la position du tag numéro "tagid".
-//--
 {
   if (!s.GotoNameTag(tag))
@@ -361,5 +344,7 @@
 
 // Renvoie l'identificateur de l'objet  - par defaut=0
-
+/*! Return the object identifier (default: return 0)
+  (used for handling of PPF I/O for objects with reference sharing).
+*/
 uint_8 
 PPersist::getMemOId() const
@@ -370,4 +355,8 @@
 // Ces deux methodes doivent etre redefinies si   getMemOId() renvoie non nul (>0)
 // ShareDataReference() et CloneSharedReference()
+/*! 
+  This method should be re-implemented if getMemOId() non zero value.
+  (used for handling of PPF I/O for objects with reference sharing).
+*/
 void 
 PPersist::ShareDataReference(PPersist & pcs)
@@ -376,4 +365,8 @@
 }
 
+/*! 
+  This method should be re-implemented if getMemOId() non zero value.
+  (used for handling of PPF I/O for objects with reference sharing).
+*/
 PPersist *
 PPersist::CloneSharedReference()
@@ -403,4 +396,17 @@
 //--
 
+/*!
+   \class SOPHYA::PInPersist
+   \ingroup BaseTools
+   This class implements the I/O read services necessary for SOPHYA
+   persistence (PPF) by extending the services provided by PPFBinaryInputStream.
+   \sa PPersist
+*/
+
+/*! Constructor from a RawInOutStream pointer
+  \param is : pointer to RawInOutStream
+  \param ad : if true, the RawInOutStream \b is is deleted by the destructor 
+  \param scan : if true, try to read the name-tags table from the end of the input stream
+*/ 
 PInPersist::PInPersist(RawInOutStream * is, bool ad, bool scan)
   : PPFBinaryInputStream(is, ad, scan)
@@ -408,4 +414,8 @@
 }
 
+/*! Constructor 
+  \param  flnm : input file name
+  \param scan : if true, try to read the name-tags table from the end of the input stream
+*/  
 PInPersist::PInPersist(string const& flnm, bool scan)
   : PPFBinaryInputStream(flnm, scan)
@@ -436,4 +446,7 @@
 }
 
+/*! Skip to next object in the streams, reads it and return 
+  the corresponding PPersist handler 
+*/
 PPersist*
 PInPersist::ReadObject()
@@ -443,4 +456,7 @@
 }
 
+/*! 
+  Tries to read in from the stream into object \b o
+*/
 void 
 PInPersist::GetObject(AnyDataObj & o)
@@ -450,4 +466,7 @@
 }
 
+/*! 
+  Tries to move to \b nametag and then read in from the stream into object \b o
+*/
 void 
 PInPersist::GetObject(AnyDataObj & o, string tagname)
@@ -458,4 +477,7 @@
 }
 
+/*! 
+  Reading of objects - used by GetObject() and ReadObject()
+*/
 PPersist*
 PInPersist::GetPPObject(AnyDataObj * po)
@@ -575,4 +597,12 @@
 
 
+/*!
+   \class SOPHYA::POutPersist
+   \ingroup BaseTools
+   This class implements the I/O write services necessary for SOPHYA
+   persistence (PPF) by extending the services provided by PPFBinaryOutputStream.
+   \sa PPersist
+*/
+
 //++
 //  POutPersist(string const& flnm, int endianness = PPersist::PPS_NATIVE)
@@ -583,4 +613,10 @@
 //	ou PPersist::PPS_BIG_ENDIAN.
 //--
+
+/*! Constructor from a RawInOutStream pointer
+  \param os : pointer to RawInOutStream
+  \param ad : if true, the RawInOutStream \b os is deleted by the destructor 
+  \param endianness : Endianness selector  PPS_NATIVE PPS_LITTLE_ENDIAN PPS_BIG_ENDIAN 
+*/ 
 POutPersist::POutPersist(RawInOutStream* os, bool ad, int endianness)
   : PPFBinaryOutputStream(os, ad, endianness)
@@ -590,4 +626,8 @@
 }
 
+/*! Constructor 
+  \param flnm : output file name 
+  \param endianness : Endianness selector  PPS_NATIVE PPS_LITTLE_ENDIAN PPS_BIG_ENDIAN 
+*/ 
 POutPersist::POutPersist(string const& flnm, int endianness)
   : PPFBinaryOutputStream(flnm, endianness)
@@ -603,4 +643,5 @@
 
 
+//! Writes the object \b o to the stream
 void
 POutPersist::PutObject(AnyDataObj & o)
@@ -614,4 +655,5 @@
 }
 
+//! Writes the nametag \b tagname and then the object \b o to the stream
 void
 POutPersist::PutObject(AnyDataObj & o, string tagname)
