X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fyoink;a=blobdiff_plain;f=src%2Fdeserializer.hh;h=f2b0bccc06d1ade59f920f120cbf42d3a262148c;hp=733ce3912f33652d20697bff046d357ba0e2581d;hb=7d15b919681bb9ec0088b4b27c6abf62d6dfb9b1;hpb=0fffd0097d7b496454413e57b398c903ecc252e4

diff --git a/src/deserializer.hh b/src/deserializer.hh
index 733ce39..f2b0bcc 100644
--- a/src/deserializer.hh
+++ b/src/deserializer.hh
@@ -44,23 +44,72 @@
 namespace dc {
 
 
-class serializable;
+class serializable;		// forward declaration
 typedef boost::shared_ptr<serializable> serializable_ptr;
 
-class deserializer_impl;
-
 class deserializer
 {
 public:
+
+	/**
+	 * Construction is initialization.  A deserializer can be constructed with
+	 * either an input stream or a string representing a filename that will be
+	 * read from.  If a stream is provided, it will not be closed after parsing,
+	 * but the parser may read past the end of usable bytes, so you should not
+	 * use a deserializer on a stream that you expect to continue to use after
+	 * the deserialization.
+	 * @param comments If true, C and C++-style comments will be allowed and
+	 * ignored by the parser.
+	 * @param check If true, UTF-8 strings will be checked for validity and an
+	 * exception thrown if such a problem exists.  Otherwise strings will not be
+	 * checked.
+	 */
+
 	deserializer(const std::string& filePath, bool comments = false,
 			bool check = false);
 	deserializer(std::istream& input, bool comments = false, bool check = false);
 
+
+	/**
+	 * Parse the object from of the stream.  The stream is considered to be
+	 * dominated by the parser and may read and discard bytes past the end of
+	 * the actual parsed object.  Only one object can be deserialized by the
+	 * deserializer.
+	 */
+
 	serializable_ptr deserialize();
 
+	/**
+	 * Used by serializable objects to parse themselves.  These methods should
+	 * generally not be used directory for deserialization.  This one returns
+	 * the next object in the queue which has been parsed.  This method may
+	 * block if more data is pending and an object has not bee constructed yet.
+	 * The caller takes ownership of the object which has been allocated with
+	 * the new operator and must therefore be sure to delete the object as
+	 * appropriated.  Null (0) will be returned by this method to signify one of
+	 * three things: 1) the end of an array, 2) the end of a map/dictionary, or
+	 * 3) there is nothing more to be obtained.  Container objects will be empty
+	 * and will have to be filled with their contained elements by repeatedly
+	 * calling this method until a null is returned.  This method will continue
+	 * to return the same value until pop() is called which will cause this
+	 * method to return the next object as expected.
+	 */
+
 	serializable* pullNext();
+
+	/**
+	 * If the object returned by pullNext() has been received successfully and
+	 * the caller is ready for the next object, this method should be called to
+	 * take that object off of the queue.
+	 */
+
 	void pop();
 
+
+	/**
+	 * This exception is thrown upon deserialization errors.
+	 */
+
 	struct exception : std::runtime_error
 	{
 		explicit exception(const std::string& what_arg) :
@@ -68,6 +117,7 @@ public:
 	};
 
 private:
+	class deserializer_impl;
 	boost::shared_ptr<deserializer_impl> impl;
 };
 
@@ -77,3 +127,5 @@ private:
 
 #endif // _DESERIALIZER_HH_
 
+/** vim: set ts=4 sw=4 tw=80: *************************************************/
+