[pclasses-cvs] pclasses2/src/s11n SIO.h,1.6,1.7

[stephan b. <sg...@us...>]

Update of /cvsroot/pclasses/pclasses2/src/s11n
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv26354/src/s11n

Modified Files:
	SIO.h 
Log Message:
Several API doc additions.

Index: SIO.h
===================================================================
RCS file: /cvsroot/pclasses/pclasses2/src/s11n/SIO.h,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- SIO.h	27 Dec 2004 20:07:18 -0000	1.6
+++ SIO.h	27 Dec 2004 23:23:23 -0000	1.7
@@ -9,6 +9,12 @@
 // This header is intended to provide the standard P::s11n interface,
 // in particular the client-side interface.
 //
+//
+// Reminder to maintainers of this code: it is perfectly fine for this
+// code to depend on any P::s11n-related code, but it is NEVER
+// acceptable for ANY non-SIO code in the P::s11n namespace to depend
+// on P::SIO!!! NEVER, EVER!
+// (EVER! Don't even consider it!)
 ////////////////////////////////////////////////////////////////////////
 
 
@@ -17,6 +23,7 @@
 #include <pclasses/s11n/s11n.h>
 #include <pclasses/s11n/io/serializers.h>
 
+
 namespace P {
 
 /**
@@ -24,6 +31,22 @@
    P::s11n-related API. Clients using s11n proxies and implementing
    serialization code may need to use the classes in P::s11n or
    possibly even P::s11n::io as well.
+
+   SIO is a fork/port of the s11n project:
+
+   http://s11n.net
+   
+   It was forked specifically to take advantage of the amazing super
+   powers which the combination of P and s11n imply :). Forks are
+   normally evil, but this fork was done by s11n's author :).
+
+   SIO is mostly API-compatible with s11nlite, but uses a different
+   data node type, so it is not 100% usage-compable. Data
+   files/streams should be freely exchangeable between SIO and
+   s11nlite, however, provided a compatible parser exists on
+   both sides of the transaction (this is likely to be the case
+   for most available Serializers, since i currently maintain
+   both SIO and s11n :).
 */
 namespace SIO
 {
@@ -32,9 +55,9 @@
 
 	   Note that it is considered poor form to use an S11nNode's
 	   API directly, as it's type and interface may change. The
-	   only guaranty the S11nNode's API gives is that
-	   NodeTraits::funcs(S11nNode &...) operations will work as
-	   expected/documented. More clearly: use NodeTraits to
+	   only guaranty the SIO API gives regarding S11nNode's API is
+	   that NodeTraits::funcname(S11nNode &...) operations will work
+	   as expected/documented. More clearly: use NodeTraits to
 	   manipulate and query nodes, not the node API directly. In
 	   fact S11nNode's useful API is all private, so you CAN'T
 	   touch it without going through NodeTraits. :) Gotcha!
@@ -42,8 +65,8 @@
 	typedef ::P::s11n::s11n_node S11nNode;
 
 	/**
-	   NodeTraits are used to view and manipulate data in S11nNode
-	   objects.
+	   NodeTraits provide the interface for fetching and
+	   manipulating S11nNode data.
 	*/
 	typedef ::P::s11n::node_traits<S11nNode> NodeTraits;
 
@@ -68,6 +91,8 @@
 
 	/**
 	   See ::P::s11n::derialize().
+
+	   The caller owns the returned object, which may be NULL.
 	*/
         template <typename SerializableType>
         SerializableType * deserialize( const S11nNode & src )
@@ -98,6 +123,8 @@
 
         /**
            See ::P::s11n::deserialize_subnode().
+
+	   The caller owns the returned object, which may be NULL.
         */
         template <typename DeserializableT>
         DeserializableT * deserializeSubnode( const S11nNode & src,
@@ -120,12 +147,16 @@
 
         /**
            See ::P::s11n::io::load_node().
+
+	   The caller owns the returned object, which may be NULL.
         */
         S11nNode * loadNode( std::istream & src );
 
 
         /**
            See ::P::s11n::io::load_node(src).
+
+	   The caller owns the returned object, which may be NULL.
         */
         S11nNode * loadNode( const std::string & src );
 
@@ -146,6 +177,8 @@
 
 	   Once IOManager support is completed this will also support
 	   URL-based lookups.
+
+	   The caller owns the returned object, which may be NULL.
         */
         SerializerInterface * serializerFor( const std::string & url );
 
@@ -165,19 +198,20 @@
 	   Uses SerializerPluginManager to load the Serializer
 	   set via serializerClass()
 
-	   The caller owns the returned pointer, which may be 0.
+	   The caller owns the returned object, which may be NULL.
 	 */
 	SerializerInterface * createSerializer();
 	/**
 	   Uses SerializerPluginManager to load a Serializer.
 
-	   The caller owns the returned pointer, which may be 0.
+	   The caller owns the returned object, which may be NULL.
 	 */
 	SerializerInterface * createSerializer( const std::string & );
 
         /**
-           Uses serialize(src,node) to serialize src then calls
-           save(n,dest). Returns true on success, false on error.
+           Uses serialize(src,node) to serialize src to a S11nNode
+	   then calls save(node,dest). Returns true on success, false
+	   on error.
         */
         template <typename SerializableT>
         bool save( const SerializableT & src, std::ostream & dest )