Add more documentation for AP_MetaClass.

git-svn-id: https://arducopter.googlecode.com/svn/trunk@1465 f9c3cf11-9bcb-44bc-f272-b75c42450872

libraries/AP_Common/AP_MetaClass.h

@@ -7,9 +7,15 @@
 //
 
 /// @file	AP_MetaClass.h
-///			Abstract meta-class from which other AP classes may inherit.
+///	@brief	An abstract base class from which other classes can inherit.
-///			Provides type introspection and some basic protocols that can
+///
-///			be implemented by subclasses.
+/// This abstract base class declares and implements functions that are
+/// useful to code that wants to know things about a class, or to operate
+/// on the class without knowing precisely what it is.
+///
+/// All classes that inherit from this class can be assumed to have these
+/// basic functions.
+///
 
 #ifndef AP_METACLASS_H
 #define AP_METACLASS_H
@@ -29,21 +35,39 @@ public:
 	/// Default constructor does nothing.
 	AP_MetaClass(void);
 
-	/// Default destructor is virtual, to ensure that all destructors
+	/// Default destructor is virtual, to ensure that all subclasses'
-	/// are called for derived classes.
+	/// destructors are virtual.  This guarantees that all destructors
+	/// in the inheritance chain are called at destruction time.
+	///
 	virtual ~AP_MetaClass();
 
-	/// Type code, unique to all instances of a given subclass.
+	/// Typedef for the ID unique to all instances of a class.
+	///
+	/// See ::meta_type_id for a discussion of class type IDs.
+	///
 	typedef uint16_t	AP_TypeID;
 
 	/// Obtain a value unique to all instances of a specific subclass.
 	///
+	/// The value can be used to determine whether two class pointers
+	/// refer to the same exact class type.  The value can also be cached
+	/// and then used to detect objects of a given type at a later point.
+	///
 	/// This is similar to the basic functionality of the C++ typeid
 	/// keyword, but does not depend on std::type_info or any compiler-
 	/// generated RTTI.
 	///
-	/// As the value is derived from the vtable address, it cannot be
+	/// The value is derived from the vtable address, so it is guaranteed
-	/// introspected outside the current state of the system.
+	/// to be unique but cannot be known until the program has been compiled
+	/// and linked.  Thus, the only way to know the type ID of a given
+	/// type is to construct an object at runtime.  To cache the type ID
+	/// of a class Foo, one would write:
+	///
+	/// AP_MetaClass::AP_TypeID	Foo_type_id;
+	///
+	/// { Foo a; Foo_type_id = a.meta_type_id(); }
+	///
+	/// This will construct a temporary Foo object a and save its type ID.
 	///
 	/// @param	p				A pointer to an instance of a subclass of AP_MetaClass.
 	/// @return					A type-unique value.
@@ -56,6 +80,10 @@ public:
 	/// enough information to construct and validate a pointer to the instance
 	/// when passed back from an untrusted source.
 	///
+	/// Handles are useful when passing a reference to an object to a client outside
+	/// the system, as they can be validated by the system when the client hands
+	/// them back.
+	///
 	typedef uint32_t	AP_MetaHandle;
 
 	/// Return a value that can be used as an external pointer to an instance
@@ -111,9 +139,17 @@ public:
 
 	/// Tests whether two objects are of precisely the same class.
 	///
-	/// Note that for p2 inheriting from p1, this will return false.
+	/// Note that in the case where p2 inherits from p1, or vice-versa, this will return
-	/// Even with RTTI not disabled, there does not seem to be enough information
+	/// false as we cannot detect these inheritance relationships at runtime.
-	/// to determine whether one class inherits from another.
+	///
+	/// In the caller's context, p1 and p2 may be pointers to any type, but we require
+	/// that they be passed as pointers to AP_MetaClass in order to make it clear that
+	/// they should be pointers to classes derived from AP_MetaClass.
+	///
+	/// No attempt is made to validate whether p1 and p2 are actually derived from
+	/// AP_MetaClass.  If p1 and p2 are equal, or if they point to non-class objects with
+	/// similar contents, or to non-AP_MetaClass derived classes with no virtual functions
+	/// this function may return true.
 	///
 	/// @param	p1				The first object to be compared.
 	/// @param	p2				The second object to be compared.
@@ -124,7 +160,11 @@ public:
 		return p1->meta_type_id() == p2->meta_type_id();
 	}
 
-	/// Cast an object to an expected class type.
+	/// Cast a pointer to an expected class type.
+	///
+	/// This function is used when a pointer is expected to be a pointer to a
+	/// subclass of AP_MetaClass, but the caller is not certain.  It will return the pointer
+	/// if it is, or NULL if it is not a pointer to the expected class.
 	///
 	/// This should be used with caution, as _typename's default constructor and
 	/// destructor will be run, possibly introducing undesired side-effects.
@@ -146,36 +186,42 @@ public:
 		return NULL;
 	}
 
-	/// Serialise the class.
+	/// Serialize the class.
 	///
-	/// Serialisation provides a mechanism for exporting the state of the class to an
+	/// Serialization stores the state of the class in an external buffer in such a
+	/// fashion that it can later be restored by unserialization.
+	///
+	/// AP_MetaClass subclasses should only implement these functions if saving and
+	/// restoring their state makes sense.
+	///
+	/// Serialization provides a mechanism for exporting the state of the class to an
 	/// external consumer, either for external introspection or for subsequent restoration.
 	///
-	/// Classes that wrap variables should define the format of their serialised data
+	/// Classes that wrap variables should define the format of their serialiaed data
 	/// so that external consumers can reliably interpret it.
 	///
 	/// @param	buf				Buffer into which serialised data should be placed.
 	/// @param	bufSize			The size of the buffer provided.
 	/// @return					The size of the serialised data, even if that data would
 	///							have overflowed the buffer.  If the return value is zero,
-	///							the class does not support serialisation.
+	///							the class does not support serialization.
 	///
 	virtual size_t				serialize(void *buf, size_t bufSize) const;
 
-	/// Unserialise the class.
+	/// Unserialize the class.
 	///
-	/// Unserialising a class from a buffer into which the class previously serialised
+	/// Unserializing a class from a buffer into which the class previously serialized
-	/// itself restores the instance to an identical state, where "identical" may be
+	/// itself restores the instance to an identical state, where "identical" is left
-	/// defined in context.
+	/// up to the class itself to define.
 	///
-	/// Classes that wrap variables should define the format of their serialised data so
+	/// Classes that wrap variables should define the format of their serialized data so
 	/// that external providers can reliably encode it.
 	///
-	/// @param	buf				Buffer containing serialised data.
+	/// @param	buf				Buffer containing serialized data.
 	/// @param	bufSize			The size of the buffer.
 	/// @return					The number of bytes from the buffer that would be consumed
-	///							unserialising the data.  If the value is less than or equal
+	///							unserializing the data.  If the value is less than or equal
-	///							to bufSize, unserialisation was successful.  If the return
+	///							to bufSize, unserialization was successful.  If the return
 	///							value is zero the class does not support unserialisation or
 	///							the data in the buffer is invalid.
 	///

libraries/AP_Common/AP_Var.h

@@ -5,6 +5,13 @@
 // Free Software Foundation; either version 2.1 of the License, or (at
 // your option) any later version.
 //
+
+/// @file	AP_Var.h
+/// @brief	A system for managing and storing variables that are of
+///			general interest to the system.
+///
+///
+
 /// The AP variable interface. This allows different types
 /// of variables to be passed to blocks for floating point
 /// math, memory management, etc.