big batch of progress

[chaz/yoink] / src / serializer.hh

diff --git a/src/serializer.hh b/src/serializer.hh
index 8e61a622bc12e97feb4e68e95ab74e5881f6c2e5..206a7930fab9903b5ad6e9acd4eb848ddfff9182 100644 (file)
--- a/src/serializer.hh
+++ b/src/serializer.hh
@@ -44,16 +44,28 @@
 namespace dc {
 
 
-class serializer_impl;
-
 class serializer
 {
 public:
+
+       /**
+        * Construction is initialization.  Use either an output stream or a string
+        * representing a path to a fill to which the serialized data will be
+        * written (replacing any previous file).
+        * @param indent If non-empty, the string's characters will be used as
+        * indentation.  Otherwise, the serialized data will not be formatted neatly
+        * but will be tightly packed.
+        */
+
        serializer(const std::string& filePath, const std::string& indent = "");
        serializer(std::ostream& output, const std::string& indent = "");
 
        ~serializer();
 
+       /**
+        * Push various types of data onto the stream.
+        */
+
        void push(long value);
        void push(double value);
        void push(bool value);
@@ -61,14 +73,32 @@ public:
        void push(const std::wstring& value);
        void pushNull();
 
+       /**
+        * Push a map onto the stream.  Each map head must be matched by a map tail.
+        */
+
        void pushMapHead();
        void pushMapTail();
 
+       /**
+        * Push an array onto the stream.  Each array head must be matched by an
+        * array tail.
+        */
+
        void pushArrayHead();
        void pushArrayTail();
 
+       /**
+        * Write any pending bytes to the stream.  This is called automatically by
+        * the destructor of this class.
+        */
+
        void flush();
 
+       /**
+        * This exception is thrown for serializer-related exceptional errors.
+        */
+
        struct exception : std::runtime_error
        {
                explicit exception(const std::string& what_arg) :
@@ -76,6 +106,7 @@ public:
        };
 
 private:
+       class serializer_impl;
        boost::shared_ptr<serializer_impl> impl;
 };
 
@@ -84,3 +115,5 @@ private:
 
 #endif // _SERIALIZER_HH_
 
+/** vim: set ts=4 sw=4 tw=80: *************************************************/
+