add some doc comments to the type-system header

src/framework/util/typesystem.h

@@ -3,19 +3,31 @@
 
 #include "../common.h"
 
+// default generic type system identifier type
 typedef const char* TYPE_IDENT;
 
-#define TYPE_DEFINE(type, value)              \
+// The macros below can be used to quickly add methods to classes which allow
-	static type GetType()                     \
+// a "poor-mans" run-time type system to be used. This type system allows for:
-	{                                         \
+//
-		static type typeName = value;         \
+//   - retrieval of a type-identifier at run-time via either:
-		return typeName;                      \
+//         object.GetTypeOf()        (instance method)      or
-	}                                         \
+//         ObjectType::GetType()     (static method)
-	type GetTypeOf() const                    \
+//
-	{                                         \
+//   - comparison of two types using either template methods (static) or 
-		return GetType();                     \
+//     variables containing type identifiers
-	}
+//         BOOL result = object.Is<ObjectType>()          or
+//         BOOL result = object.Is(objectTypeId)
+//
+//   - "safe" casting - if the type doesn't match, NULL is returned
+//         ObjectType* type = object.As<ObjectType>()
 
+
+/**
+ * Adds methods to a base type class that implement type identifier retrieval
+ * (which will be overridden by subclasses) and type comparison and safe
+ * casting between types.
+ * @param type the compiler type used for the type identifier
+ */
 #define TYPE_BASE(type)                                                        \
 	virtual type GetTypeOf() const = 0;                                        \
 	template<class T> BOOL Is() const                                          \
@@ -41,7 +53,27 @@ typedef const char* TYPE_IDENT;
 			return NULL;                                                       \
 	}
 
-#define TYPE_DEFINE_DEFAULT(value)     TYPE_DEFINE(TYPE_IDENT, value)
+/**
+ * Adds methods used by subclasses of a type that defines methods for
+ * type identifier retrieval and comparisons
+ * @param type the compiler type used for the type identifier for this class
+ * @param value the value to assign to this class's type identifier
+ */
+#define TYPE_DEFINE(type, value)                                               \
+	static type GetType()                                                      \
+	{                                                                          \
+		static type typeName = value;                                          \
+		return typeName;                                                       \
+	}                                                                          \
+	type GetTypeOf() const                                                     \
+	{                                                                          \
+		return GetType();                                                      \
+	}
+
+// these macros work the same as the above two, but they will use
+// the TYPE_IDENT typedef defined above as the type identifier compiler type
+
 #define TYPE_BASE_DEFAULT              TYPE_BASE(TYPE_IDENT)
+#define TYPE_DEFINE_DEFAULT(value)     TYPE_DEFINE(TYPE_IDENT, value)
 
 #endif