X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=src%2Fserializer.hh;h=206a7930fab9903b5ad6e9acd4eb848ddfff9182;hp=0690d6c020ef1cc4922e891f3b6b14db6ffdb7e5;hb=7d15b919681bb9ec0088b4b27c6abf62d6dfb9b1;hpb=79b5f738f2e38acb60cda7e09f54802933a17105

diff --git a/src/serializer.hh b/src/serializer.hh
index 0690d6c..206a793 100644
--- 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,21 +73,40 @@ 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();
 
-	struct generator_error : std::runtime_error
+	/**
+	 * This exception is thrown for serializer-related exceptional errors.
+	 */
+
+	struct exception : std::runtime_error
 	{
-		explicit generator_error(const std::string& what_arg) :
+		explicit exception(const std::string& what_arg) :
 			std::runtime_error(what_arg) {}
 	};
 
 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: *************************************************/
+