--- trunk/OOPSE-4/src/utils/GenericFactory.hpp	2004/10/24 07:55:48	1641
+++ trunk/OOPSE-4/src/utils/GenericFactory.hpp	2004/10/28 22:26:32	1681
@@ -31,6 +31,7 @@
  */
 #ifndef UTIL_GENERICFACTORY_HPP
 #define UTIL_GENERICFACTORY_HPP
+#include <cassert>
 #include <map>
 #include <string>
 #include <vector>
@@ -47,6 +48,7 @@ namespace oopse {
  * @param Creator  the callable entity that creates objects. This type must support operator(),
  * taking no parameters and returning a pointer to Object. Default type is function pointer.
  *
+ * Usage:
  * @code
  * //Shape class
  * class Shape {
@@ -67,7 +69,9 @@ namespace oopse {
  * }
  *
  * //register createLine
- * ShapeFactory::getInstance()->registerCreator("Line", createLine);
+ * //note: must put ShapeFactory::getInstance()->registerCreator("Line", createLine) on the right
+ * //hand side, otherwise the compiler will consider it as a function declaration
+ * const bool registeredLine = ShapeFactory::getInstance()->registerCreator("Line", createLine);
  *
  * //Circle class
  * class Circle : public Shape{
@@ -80,12 +84,45 @@ namespace oopse {
  * }
  *
  * //register createCircle
- * ShapeFactory::getInstance()->registerCreator("Circle", createCircle); 
+ * const bool registeredCircle = ShapeFactory::getInstance()->registerCreator("Circle", createCircle); 
  *
  * //create object by ident
  * Line* line = ShapeFactory::getInstance()->createObject("Line");
  * Circle* circle = ShapeFactory::getInstance()->createObject("Circle"); 
  * @endcode
+ *
+ * Or the user can use predefined macro DECLARE_CREATOR and REGISTER_CREATOR
+ * @code
+ * //Shape class
+ * class Shape {
+ * ...
+ * };
+ * 
+ * //instantiating a new object factory
+ * typedef GenericFactory<Shape> ShapeFactory;
+ *
+ * //Line class
+ * class Line : public Shape{
+ * ...
+ * };
+ *
+ * //declare function using macro 
+ * DECLARE_CREATOR(Shape, Line)
+ * 
+ * //register using macro
+ * REGISTER_CREATOR(ShapeFactory, "Line", Line);
+ 
+ * //Circle class
+ * class Circle : public Shape{
+ * ...
+ * };
+ *
+ * //declare function using macro 
+ * DECLARE_CREATOR(Shape, Circle)
+ * 
+ * //register using macro
+ * REGISTER_CREATOR(ShapeFactory, "Circle", Circle);
+ * @endcode
  */
 template<class Object, typename IdentType = std::string, typename Creator = Object* (*)()>
 class GenericFactory {
@@ -130,11 +167,12 @@ class GenericFactory {
          * corresponding creator for the type identifier and returns its result. 
          * @return a pointer of the concrete object, return NULL if no creator is registed for 
          * creating this concrete object
-         * @id the identification of the concrete object
+         * @param id the identification of the concrete object
          */
         Object* createObject(const IdentType& id) {
             typename CreatorMapType::iterator i = creatorMap_.find(id);
             if (i != creatorMap_.end()) {
+                //invoke functor to create object
                 return (i->second)();
             } else {
                 return NULL;
@@ -161,7 +199,7 @@ class GenericFactory {
         CreatorMapType creatorMap_;
 };
 
-/** write out all of the type identifier to a output stream */
+/** write out all of the type identifiers to an output stream */
 template<typename O, typename I, typename C>
 std::ostream& operator <<(std::ostream& o, GenericFactory<O, I, C>& factory) {
     std::vector<I> idents;
@@ -181,11 +219,16 @@ GenericFactory<Object,IdentType,Creator>* GenericFacto
 template<class Object, typename IdentType,typename Creator>
 GenericFactory<Object,IdentType,Creator>* GenericFactory<Object,IdentType,Creator>::instance_ ; 
 
+
 #define DECLARE_CREATOR(abstractObject, concreteObject) \
-    abstractObject* create##concreteObject(){\
+    inline abstractObject* create##concreteObject(){\
         return new concreteObject;\
     }
 
+#define REGISTER_CREATOR(factory, ident, concreteObject) \
+        const bool registered##concreteObject = factory::getInstance()->registerCreator(ident, create##concreteObject); 
+
+
 }//namespace oopse
 #endif //UTIL_GENERICFACTORY_HPP