From 1fa3ca5f24c018126333ca2d6609730e1ae17386 Mon Sep 17 00:00:00 2001
From: Mike Buland <eichlan@xagasoft.com>
Date: Tue, 10 Apr 2007 21:48:23 +0000
Subject: Added more comments, help, and socket actually reads and writes some,
 but it's not done.  I need to decide how I want to do the buffering...

---
 src/archive.h | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

(limited to 'src/archive.h')

diff --git a/src/archive.h b/src/archive.h
index 9ac3303..2f782d3 100644
--- a/src/archive.h
+++ b/src/archive.h
@@ -9,6 +9,53 @@
 
 namespace Bu
 {
+	/**
+	 * Provides a framework for serialization of objects and primitives.  The
+	 * archive will handle any basic primitive, a few special types, like char *
+	 * strings, as well as STL classes and anything that inherits from the
+	 * Archival class.  Each Archive operates on a Stream, so you can send the
+	 * data using an Archive almost anywhere.
+	 *
+	 * In order to use an Archive to store something to a file, try something
+	 * like:
+	 *@code
+     * File sOut("output", "wb"); // This is a stream subclass
+	 * Archive ar( sOut, Archive::save );
+	 * ar << myClass;
+	 @endcode
+	 * In this example myClass is any class that inherits from Archival.  When
+	 * the storage operator is called, the Archival::archive() function in the
+	 * myClass object is called with a reference to the Archive.  This can be
+	 * handled in one of two ways:
+	 *@code
+	 * void MyClass::archive( Archive &ar )
+	 * {
+	 * 	ar && sName && nAge && sJob;
+	 * }
+	 @endcode
+	 * Here we don't worry about weather we're loading or saving by using the
+	 * smart && operator.  This allows us to write very consistent, very simple
+	 * archive functions that really do a lot of work.  If we wanted to do
+	 * something different in the case of loading or saving we would do:
+	 *@code
+	 * void MyClass::archive( Archive &ar )
+	 * {
+	 * 	if( ar.isLoading() )
+	 * 	{
+	 * 		ar >> sName >> nAge >> sJob;
+	 * 	} else
+	 * 	{
+	 * 		ar << sName << nAge << sJob;
+	 * 	}
+	 * }
+	 @endcode
+	 * Archive currently does not provide facility to make fully portable
+	 * archives.  For example, it will not convert between endianness for you,
+	 * nor will it take into account differences between primitive sizes on
+	 * different platforms.  This, at the moment, is up to the user to ensure.
+	 * One way of dealing with the latter problem is to make sure and use
+	 * explicit primitive types from the stdint.h header, i.e. int32_t.
+	 */
 	class Archive
 	{
 	private:
-- 
cgit v1.2.3