Changeset 7372

Timestamp:

Sep 7, 2010, 12:58:52 AM (14 years ago)

Author:

landauf

Message:

enhanced documentation of some core classes and added examples

Location:

code/branches/doc/src/libraries/core

Files:

• BaseObject.h (modified) (1 diff)
• ClassFactory.h (modified) (2 diffs)
• ClassTreeMask.cc (modified) (8 diffs)
• ClassTreeMask.h (modified) (15 diffs)
• CommandLineParser.h (modified) (1 diff)
• ConfigValueContainer.h (modified) (4 diffs)
• ConfigValueIncludes.h (modified) (1 diff)
• CoreIncludes.h (modified) (4 diffs)
• Event.cc (modified) (1 diff)
• Event.h (modified) (2 diffs)
• EventIncludes.h (modified) (1 diff)
• Identifier.cc (modified) (2 diffs)
• Identifier.h (modified) (9 diffs)
• Iterator.h (modified) (3 diffs)
• Language.h (modified) (7 diffs)
• MetaObjectList.h (modified) (3 diffs)
• ObjectList.h (modified) (6 diffs)
• ObjectListBase.cc (modified) (1 diff)
• ObjectListBase.h (modified) (6 diffs)
• ObjectListIterator.h (modified) (4 diffs)
• OrxonoxClass.h (modified) (6 diffs)
• SubclassIdentifier.h (modified) (11 diffs)
• Super.h (modified) (2 diffs)

code/branches/doc/src/libraries/core/BaseObject.h

@@ -59 +59 @@
     class Level;
 
-    //! The BaseObject is the parent of all classes representing an instance in the game.
+    /// The BaseObject is the parent of all classes representing an instance in the game.
     class _CoreExport BaseObject : virtual public OrxonoxClass
     {

code/branches/doc/src/libraries/core/ClassFactory.h

@@ -50 +50 @@
     // ###       Factory       ###
     // ###########################
-    //! Base-class of ClassFactory.
+    /// Base-class of ClassFactory.
     class _CoreExport Factory
     {
@@ -61 +61 @@
     // ###      ClassFactory       ###
     // ###############################
-    //! The ClassFactory is able to create new objects of a specific class.
+    /// The ClassFactory is able to create new objects of a specific class.
     template <class T>
     class ClassFactory : public Factory

code/branches/doc/src/libraries/core/ClassTreeMask.cc

@@ -29 +29 @@
 /**
     @file
-    @brief Implementation of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
+    @brief Implementation of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
 */
 
@@ -93 +93 @@
     /**
         @brief Adds a new subnode to the list of subnodes.
-        @param subnode The new subnode
     */
     void ClassTreeMaskNode::addSubnode(ClassTreeMaskNode* subnode)
@@ -178 +177 @@
     /**
         @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
-        @return The pointer to the node
     */
     ClassTreeMaskNode* ClassTreeMaskIterator::operator*() const
@@ -187 +185 @@
     /**
         @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
-        @return The pointer to the node
     */
     ClassTreeMaskNode* ClassTreeMaskIterator::operator->() const
@@ -196 +193 @@
     /**
         @brief Returns true if the stack is empty, meaning we've reached the end of the tree.
-        @return True if we've reached the end of the tree
     */
     ClassTreeMaskIterator::operator bool() const
@@ -205 +201 @@
     /**
         @brief Compares the current node with the given one and returns true if they match.
-        @param compare The node to compare with
-        @return The result of the comparison (true if they match)
     */
     bool ClassTreeMaskIterator::operator==(ClassTreeMaskNode* compare) const
@@ -218 +212 @@
     /**
         @brief Compares the current node with the given one and returns true if they don't match.
-        @param compare The node to compare with
-        @return The result of the comparison (true if they don't match)
     */
     bool ClassTreeMaskIterator::operator!=(ClassTreeMaskNode* compare) const
@@ -242 +234 @@
 
     /**
-        @brief Copyconstructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
-        @param other The other mask
+        @brief Copy-constructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
     */
     ClassTreeMask::ClassTreeMask(const ClassTreeMask& other)

code/branches/doc/src/libraries/core/ClassTreeMask.h

@@ -30 +30 @@
     @file
     @ingroup Class
-    @brief Definition of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
-
-    ClassTreeMask is a class to define a mask of the class-tree beginning with BaseObject.
+    @brief Declaration of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
+
+    ClassTreeMask is a class to define a mask of the class-tree beginning with orxonox::BaseObject.
     You can include or exclude classes by calling the corresponding functions with the
-    Identifier of the class.
+    orxonox::Identifier of the class. This mask can then be used to filter out objects that
+    are instances of classes which aren't included in the tree, for example when Loading a
+    level file or if a Trigger should be triggered by only a few classes.
+
+    See the description of orxonox::ClassTreeMask for a short example.
 
     You can work with a ClassTreeMask in the sense of the set-theory, meaning that you can create
     unions, intersections, complements and differences by using overloaded operators.
 
-
+    @par Tree structure
 
     The ClassTreeMask is internally represented by a tree. The nodes in the tree are
@@ -46 +50 @@
     nodes changing the mask. By adding new rules, the tree gets reordered dynamically.
 
-    Adding a new rule overwrites all rules assigned to inherited classes. Use overwrite = false
+    Adding a new rule overwrites all rules assigned to inherited classes. Use <tt>overwrite = false</tt>
     if you don't like this feature. Useless rules that don't change the information of the mask
-    aren't saved in the internal tree. Use clean = false if you wan't to save them.
-
-    With overwrite = false and clean = false it doesn't matter in which way you create the mask.
-    You can manually drop useless rules from the tree by calling clean().
-
-
-
-    Because of the complicated shape of the internal tree, there is an iterator to iterate
-    through all ClassTreeMaskNodes of a mask. It starts with the BaseObject and moves on to
-    the first subclass until it reaches a leaf of the tree. Then the iterator moves one step
-    back and iterates to the second subclass. If there are no more subclasses, it steps another
-    step back, and so on.
-
-    Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
-    The ClassTreeMaskIterator would move trough the tree in the following order:
-    BaseObject, A, A1, A2, B, B1, B2.
-
-    Note that the iterator doesn't move trough the whole class-tree, but only through the
-    internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
+    aren't saved in the internal tree. Use <tt>clean = false</tt> if you still want to save them.
+
+    With <tt>overwrite = false</tt> and <tt>clean = false</tt> it doesn't matter in which order
+    you create the mask. You can manually drop useless rules from the tree by calling
+    @ref orxonox::ClassTreeMask::clean() "clean()".
+
+    @par Objects
+
+    To iterate through all objects of the classes that were included by a ClassTreeMask,
+    use orxonox::ClassTreeMaskObjectIterator. The description of this class also contains
+    a short example of how to use it.
 */
 
@@ -84 +80 @@
     // ###      ClassTreeMaskNode      ###
     // ###################################
-    //! The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
     /**
+        @brief The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
+
         The ClassTreeMaskNode is used to store the rule (included or excluded) for a given
         class (described by the corresponding Identifier). The nodes are used in the internal
@@ -106 +103 @@
             void addSubnode(ClassTreeMaskNode* subnode);
 
-            /** @brief Tells if the rule is "included" or not. @return The rule: true = included, false = excluded */
+            /// Tells if the rule is "included" or not.
             inline bool isIncluded() const { return this->bIncluded_; }
-            /** @brief Tells if the rule is "excluded" or not. @return The inverted rule: true = excluded, false = included */
+            /// Tells if the rule is "excluded" or not.
             inline bool isExcluded() const { return (!this->bIncluded_); }
 
-            /** @brief Returns the Identifier of the class the rule refers to. @return The Identifier representing the class */
+            /// Returns the Identifier of the class the rule refers to.
             inline const Identifier* getClass() const { return this->subclass_; }
 
-            /** @brief Returns true if the Node has some subnodes. */
+            /// Returns true if the node has some subnodes.
             inline bool hasSubnodes() const { return !this->subnodes_.empty(); }
 
@@ -120 +117 @@
             void deleteAllSubnodes();
 
-            const Identifier* subclass_;                //!< The Identifier of the subclass the rule refers to
-            bool bIncluded_;                            //!< The rule: included or excluded
-            std::list<ClassTreeMaskNode*> subnodes_;    //!< A list containing all subnodes in the tree
+            const Identifier* subclass_;                ///< The Identifier of the subclass the rule refers to
+            bool bIncluded_;                            ///< The rule: included or excluded
+            std::list<ClassTreeMaskNode*> subnodes_;    ///< A list containing all subnodes of this node
     };
 
@@ -129 +126 @@
     // ###    ClassTreeMaskIterator    ###
     // ###################################
-    //! The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask, containing the rules.
     /**
+        @brief The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask which contains the rules.
+
         Because of the complicated shape of the internal rule-tree of ClassTreeMask, an
         iterator is used to move through all nodes of the tree. It starts with the BaseObject
@@ -136 +134 @@
         iterator moves one step back and iterates to the second subclass. If there are no more
         subclasses, it steps another step back, and so on.
+
+        Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
+        The ClassTreeMaskIterator would move trough the tree in the following order:
+        BaseObject, A, A1, A2, B, B1, B2.
+
+        Note that the iterator doesn't move trough the whole class-tree, but only through the
+        internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
     */
     class _CoreExport ClassTreeMaskIterator
@@ -151 +156 @@
 
         private:
-            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    //!< A stack to store list-iterators
-            std::list<ClassTreeMaskNode*> rootlist_;                                                                            //!< A list for internal use (it only stores the root-node)
+            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    ///< A stack to store list-iterators
+            std::list<ClassTreeMaskNode*> rootlist_;                                                                            ///< A list for internal use (it only stores the root-node)
     };
 
@@ -159 +164 @@
     // ###        ClassTreeMask        ###
     // ###################################
-    //! The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
     /**
+        @brief The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
+
         With a ClassTreeMask, you can include or exclude subtrees of the class-tree, starting
         with a given subclass, described by the corresponding Identifier. To minimize the size
         of the mask, the mask saves only relevant rules. But you can manually add rules that
-        don't change the information of the mask by using clean = false. If you want to drop
+        don't change the information of the mask by using <tt>clean = false</tt>. If you want to drop
         useless rules, call the clean() function.
+
+        Example:
+        @code
+        ClassTreeMask mymask;
+        mymask.exclude(Class(A));
+        mymask.exclude(Class(B));
+        mymask.include(Class(ChildOfA));
+        @endcode
+
+        In this example, the classes A and B are excluded from the mask, but one of the child
+        classes of A is included again.
     */
     class _CoreExport ClassTreeMask
@@ -190 +207 @@
             bool isExcluded(const Identifier* subclass) const;
 
-            /** @brief Begin of the ClassTreeMaskObjectIterator. */
+            /// Begin of the ClassTreeMaskObjectIterator.
             inline const ClassTreeMask& begin() const { return (*this); }
-            /** @brief End of the ClassTreeMaskObjectIterator. */
+            /// End of the ClassTreeMaskObjectIterator.
             inline BaseObject*          end()   const { return 0; }
 
@@ -229 +246 @@
             bool nodeExists(const Identifier* subclass);
 
-            ClassTreeMaskNode* root_;   //!< The root-node of the internal rule-tree, usually BaseObject
+            ClassTreeMaskNode* root_;   ///< The root-node of the internal rule-tree, usually BaseObject
     };
 
@@ -236 +253 @@
     // ### ClassTreeMaskObjectIterator ###
     // ###################################
-    //! The ClassTreeMaskObjectIterator iterates through all objects of all classes, included by a ClassTreeMask.
     /**
-        The ClassTreeMaskObjectIterator iterates through all objects of all classes,
-        included by a ClassTreeMask. This is done the following way:
-
+        @brief The ClassTreeMaskObjectIterator iterates through all objects of the classes that were included by a ClassTreeMask.
+
+        This is done the following way:
+        @code
         ClassTreeMask mask;
         for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
             it->doSomething();
-
-        Note: The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
+        @endcode
+
+        @note The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
               you want to use another class, you should use a dynamic_cast.
 
-        Performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
+        The performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
         subclasses of included classes. Of course you can still exlucde subclasses, but
         if this is done more often, we need a new implementation using a second ObjectList
@@ -256 +274 @@
     {
         public:
-            /** @brief Defaultconstructor: Does nothing. */
+            /// Default-constructor: Does nothing.
             inline ClassTreeMaskObjectIterator() {}
-            /** @brief Constructor: Initializes the iterator from a given ClassTreeMask. @param mask The mask */
+            /// Copy-Constructor: Initializes the iterator from another ClassTreeMask.
             inline ClassTreeMaskObjectIterator(const ClassTreeMask& mask) { (*this) = mask; }
 
@@ -265 +283 @@
             const ClassTreeMaskObjectIterator& operator++();
 
-            /** @brief Returns true if the ClassTreeMaskObjectIterator points at the given object. @param pointer The pointer of the object */
+            /// Returns true if the ClassTreeMaskObjectIterator points at the given object.
             inline bool operator==(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) == pointer) || (!this->objectIterator_ && pointer == 0); }
-            /** @brief Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object. @param pointer The pointer of the object */
+            /// Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object.
             inline bool operator!=(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) != pointer) || (!this->objectIterator_ && pointer != 0); }
-            /** @brief Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end. */
+            /// Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end.
             inline operator bool() const { return (this->objectIterator_); }
-            /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
+            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
             inline BaseObject* operator*() const { return (*this->objectIterator_); }
-            /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
+            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
             inline BaseObject* operator->() const { return (*this->objectIterator_); }
 
@@ -279 +297 @@
             void create(ClassTreeMaskNode* node);
 
-            std::list<std::pair<const Identifier*, bool> >           subclasses_;       //!< A list of all Identifiers through which objects the iterator should iterate
-            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; //!< The current class of the iterator
-            Iterator<BaseObject>                                     objectIterator_;   //!< The current object of the iterator
+            std::list<std::pair<const Identifier*, bool> >           subclasses_;       ///< A list of all Identifiers through which objects the iterator should iterate
+            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; ///< The current class of the iterator
+            Iterator<BaseObject>                                     objectIterator_;   ///< The current object of the iterator
     };
 }

code/branches/doc/src/libraries/core/CommandLineParser.h

@@ -36 +36 @@
     @file
     @ingroup Config CmdArgs
+    @brief Declaration of CommandLineParser and CommandLineArgument, definition of the SetCommandLineArgument() macros.
 */
 

code/branches/doc/src/libraries/core/ConfigValueContainer.h

@@ -30 +30 @@
     @file
     @ingroup Config ConfigFile
-    @brief Definition of the ConfigValueContainer class.
+    @brief Declaration of the ConfigValueContainer class.
 
     The ConfigValueContainer class contains all needed information about a configurable variable:
@@ -79 +79 @@
 
 
-    //! The ConfigValuecontainer contains all needed information about a configurable variable.
     /**
+        @brief The ConfigValuecontainer contains all needed information about a configurable variable.
+
         The ConfigValueContainer class contains all needed information about a configurable variable:
          - the name of the variable
@@ -216 +217 @@
             }
 
-            /** @brief Returns the name of this container. */
+            /// Returns the name of this container.
             inline const std::string& getName() const
                 { return this->varname_; }
-            /** @brief Returns the name of the section this config value is in. */
+            /// Returns the name of the section this config value is in.
             inline const std::string& getSectionName() const
                 { return this->sectionname_; }
-            /** @brief Returns the associated identifier (can be NULL). */
+            /// Returns the associated identifier (can be NULL).
             inline Identifier* getIdentifier() const
                 { return this->identifier_; }
-            /** @brief Returns true if this config-value is a vector */
+            /// Returns true if this config-value is a vector.
             inline bool isVector() const
                 { return this->bIsVector_; }
-            /** @brief Returns the vectors size (or zero if it's not a vector). */
+            /// Returns the vectors size (or zero if it's not a vector).
             inline unsigned int getVectorSize() const
                 { return this->valueVector_.size(); }
@@ -268 +269 @@
             void update();
 
-            /** @brief Converts the config-value to a string. @return The string */
+            /// Converts the config-value to a string.
             inline std::string toString() const
                 { return this->value_; }
-            /** @brief Returns the typename of the assigned config-value. @return The typename */
+            /// Returns the typename of the assigned config-value.
             inline std::string getTypename() const
                 { return this->value_.getTypename(); }

code/branches/doc/src/libraries/core/ConfigValueIncludes.h

@@ -33 +33 @@
 
 /**
-@file
-@ingroup Config ConfigFile
-@brief
-    Definition of macros and functions for config-values.
+    @file
+    @ingroup Config ConfigFile
+    @brief Definition of macros and functions for config-values.
+
+    An example of how to use SetConfigValue():
+
+    Definition of a class in the header-file:
+    @code
+    class MyClass : public BaseObject
+    {
+        public:
+            MyClass();              // Constructor
+            void setConfigValues(); // Inherited function
+
+            const std::string& getName()
+                { return this->name_; }
+
+            float getVersion()
+                { return this->version_; }
+
+        private:
+            std::string name_;
+            float version_;
+    };
+    @endcode
+
+    Implementation of the class source-file:
+    @code
+    MyClass::MyClass()
+    {
+        // Macro-call to create an Identifier
+        RegisterObject(MyClass);
+
+        // Function-call to assign the config-values to the new object
+        this->setConfigValues();
+    }
+
+    void MyClass::setConfigValues()
+    {
+        SetConfigValue(name_, "Orxonox").description("The name of the game");
+        SetConfigValue(version_, "1.0").description("The version-number");
+    }
+    @endcode
+
+    Extract of orxonox.ini:
+    @code
+    [MyClass]
+    name_ = "Orxonox"
+    version_ = 1.1 // We have changed this value from 1.0 to 1.1
+    @endcode
+
+    Some other code:
+    @code
+    MyObject orxonoxobject;
+    std::cout << "Name:    " << orxonoxobject.getName() << std::endl;
+    std::cout << "Version: " << orxonoxobject.getVersion() << std::endl;
+    @endcode
+
+    Output:
+    @code
+    Name:    Orxonox
+    Version: 1.1
+    @endcode
 */
 

code/branches/doc/src/libraries/core/CoreIncludes.h

@@ -37 +37 @@
     @brief Definition of macros for Identifiers
 
-    Every class needs the RegisterObject(class) macro in its constructor. If the class is an interface
-    or the BaseObject itself, it needs the macro RegisterRootObject(class) instead.
+    Every class needs the @c RegisterObject(class) macro in its constructor. If the class is an interface
+    or the @c BaseObject itself, it needs the macro @c RegisterRootObject(class) instead.
 
-    To allow the object being created through the factory, use the CreateFactory(class) macro outside
-    the of the class implementation, so it gets executed before main().
+    To allow the object being created through the factory, use the @c CreateFactory(class) macro outside
+    of the class implementation, so it gets executed statically before @c main(). This will at the same time
+    register @a class in the class-hierarchy. If you don't want @a class to be loadable, but still
+    register it, call @c CreateUnloadableFactory(class).
+
+    Example:
+    @code
+    // Create the factory for MyClass
+    CreateFactory(MyClass);
+
+    // Constructor:
+    MyClass::MyClass()
+    {
+        // Register the object in the Identifier of MyClass
+        RegisterObject(MyClass);
+    }
+    @endcode
+
+    This file also defines a number of other useful macros, like, for example, @c Class(class) which
+    returns the @ref orxonox::Identifier "Identifier" of @a class, or @c ClassByString("class") which
+    returns the Identifier of a class with name @a "class".
+
+    Example:
+    @code
+    // Assigns the Identifier of MyClass
+    Identifier* identifier = Class(MyClass);
+    @endcode
+    @code
+    // Assigns the Identifier of a class named "MyClass"
+    Identifier* identifier = ClassByString("MyClass");
+    @endcode
 */
 
@@ -57 +86 @@
 
 /**
-    @brief Intern macro, containing the common parts of RegisterObject and RegisterRootObject.
+    @brief Intern macro, containing the common parts of @c RegisterObject and @c RegisterRootObject.
     @param ClassName The name of the class
-    @param bRootClass True if the class is directly derived from OrxonoxClass
+    @param bRootClass True if the class is directly derived from orxonox::OrxonoxClass
 */
 #define InternRegisterObject(ClassName, bRootClass) \
@@ -68 +97 @@
 
 /**
-    @brief RegisterObject - with and without debug output.
+    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
     @param ClassName The name of the class
 */
@@ -75 +104 @@
 
 /**
-    @brief RegisterRootObject - with and without debug output.
+    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
     @param ClassName The name of the class
+
+    In contrast to RegisterObject, this is used for classes that inherit directly from
+    orxonox::OrxonoxClass, namely all interfaces and orxonox::BaseObject.
 */
 #define RegisterRootObject(ClassName) \

code/branches/doc/src/libraries/core/Event.cc

@@ -26 +26 @@
  *
  */
+
+/**
+    @file
+    @brief Implementation of the classes Event and EventState.
+*/
 
 #include "Event.h"

code/branches/doc/src/libraries/core/Event.h

@@ -35 +35 @@
     @file
     @ingroup Event
+    @brief Declaration of the classes Event and EventState.
 */
 
@@ -64 +65 @@
         An event state is a state of an object, which can be changed by events.
         Event states are changed through functions. Possible functions headers for set event states are:
-         - memoryless state: function()
-         - boolean state:    function(bool state)
-         - individual state: function(bool state, SomeClass originator)
+         - memoryless state: <tt>function()</tt>
+         - boolean state:    <tt>function(bool state)</tt>
+         - individual state: <tt>function(bool state, SomeClass originator)</tt>
 
         Note that SomeClass may be any class deriving from BaseObject. You will not receive events from originators of other classes.
-        The actual class for SomeClass must be specified as the second argument of the XMLPortEventState macro.
+        The actual class for SomeClass must be specified as the second argument of the XMLPortEventState() macro.
 
         The this pointer of the affected object is hidden in the functors, because the events are processed in the BaseObject, but some

code/branches/doc/src/libraries/core/EventIncludes.h

@@ -30 +30 @@
     @file
     @ingroup Event
+    @brief Definition of the XMLPortEventState() macro, as well as some more useful macros.
 */
 

code/branches/doc/src/libraries/core/Identifier.cc

@@ -217 +217 @@
     /**
         @brief Sets the name of the class.
-        @param name The name
     */
     void Identifier::setName(const std::string& name)
@@ -253 +252 @@
     /**
         @brief Sets the network ID to a new value and changes the entry in the ID-Identifier-map.
-        @param id The new network ID
     */
     void Identifier::setNetworkID(uint32_t id)

code/branches/doc/src/libraries/core/Identifier.h

@@ -35 +35 @@
     @file
     @ingroup Class Identifier
-    @brief Definition of the Identifier class, definition and implementation of the ClassIdentifier class.
-
-    The Identifier contains all needed information about the class it belongs to:
-     - the name
-     - a list with all objects
-     - parents and children
-     - the factory (if available)
-     - the networkID that can be synchronised with the server
-     - all configurable variables (if available)
-
-    Every object has a pointer to the Identifier of its class. This allows the use isA(...),
-    isExactlyA(...), isChildOf(...) and isParentOf(...).
-
-    To create the class-hierarchy, the Identifier has some intern functions and variables.
-
-    Every Identifier is in fact a ClassIdentifier, but they are derived from Identifier.
+    @brief Declaration of Identifier, definition of ClassIdentifier<T>.
+
+    @anchor IdentifierExample
+
+    An Identifier "identifies" the class of an object. It contains different information about
+    the class: Its name and ID, a list of all instances of this class, a factory to create new
+    instances of this class, and more.
+
+    It also contains information about the inheritance of this class: It stores a list of the
+    Identifiers of all parent-classes as well as a list of all child-classes. These relationships
+    can be tested using functions like @c isA(), @c isChildOf(), @c isParentOf(), and more.
+
+    Every Identifier is in fact a ClassIdentifier<T> (where T is the class that is identified
+    by the Identifier), Identifier is just the common base-class.
+
+    Example:
+    @code
+    MyClass* object = new MyClass();                                            // create an instance of MyClass
+
+    object->getIdentifier()->getName();                                         // returns "MyClass"
+
+    BaseObject* other = object->getIdentifier()->fabricate(0);                  // fabricates a new instance of MyClass
+
+
+    // iterate through all objects of type MyClass:
+    ObjectListBase* objects = object->getIdentifier()->getObjects();            // get a pointer to the object-list
+    int count;
+    for (Iterator<BaseObject> it = objects.begin(); it != objects.end(); ++it)  // iterate through the objects
+        ++count;
+    COUT(0) << count << std::endl;                                              // prints "2" because we created 2 instances of MyClass so far
+
+
+    // test the class hierarchy
+    object->getIdentifier()->isA(Class(MyClass));                               // returns true
+    object->isA(Class(MyClass));                                                // returns true (short version)
+
+    object->isA(Class(BaseClass));                                              // returns true if MyClass is a child of BaseClass
+
+    Class(ChildClass)->isChildOf(object->getIdentifier());                      // returns true if ChildClass is a child of MyClass
+    @endcode
 */
 
@@ -76 +100 @@
     // ###       Identifier        ###
     // ###############################
-    //! The Identifier is used to identify the class of an object and to store information about the class.
-    /**
-        The Identifier contains all needed information about the class it belongs to:
-         - the name
-         - a list with all objects
-         - parents and children
-         - the factory (if available)
-         - the networkID that can be synchronised with the server
-         - all configurable variables (if available)
-
-        Every object has a pointer to the Identifier of its class. This allows the use isA(...),
-        isExactlyA(...), isChildOf(...) and isParentOf(...).
-
-        You can't directly create an Identifier, it's just the base-class for ClassIdentifier.
+    /**
+        @brief The Identifier is used to identify the class of an object and to store information about the class.
+
+        Each Identifier stores information about one class. The Identifier can then be used to identify
+        this class. On the other hand it's also possible to get the corresponding Identifier of a class,
+        for example by using the macro Class().
+
+        @see See @ref IdentifierExample "Identifier.h" for more information and some examples.
+
+        @note You can't directly create an Identifier, it's just the base-class of ClassIdentifier<T>.
     */
     class _CoreExport Identifier
     {
         public:
-            /** @brief Returns the name of the class the Identifier belongs to. @return The name */
+            /// Returns the name of the class the Identifier belongs to.
             inline const std::string& getName() const { return this->name_; }
             void setName(const std::string& name);
 
-            /** @brief Returns the network ID to identify a class through the network. @return the network ID */
+            /// Returns the network ID to identify a class through the network.
             inline const uint32_t getNetworkID() const { return this->networkID_; }
             void setNetworkID(uint32_t id);
 
-            /** @brief Returns the unique ID of the class */
+            /// Returns the unique ID of the class.
             FORCEINLINE unsigned int getClassID() const { return this->classID_; }
 
-            /** @brief Returns the list of all existing objects of this class. @return The list */
+            /// Returns the list of all existing objects of this class.
             inline ObjectListBase* getObjects() const { return this->objects_; }
 
-            /** @brief Sets the Factory. @param factory The factory to assign */
+            /// Sets the Factory.
             inline void addFactory(Factory* factory) { this->factory_ = factory; }
-            /** @brief Returns true if the Identifier has a Factory. */
+            /// Returns true if the Identifier has a Factory.
             inline bool hasFactory() const { return (this->factory_ != 0); }
 
             BaseObject* fabricate(BaseObject* creator);
 
-            /** @brief Returns true if the class can be loaded through XML. */
+            /// Returns true if the class can be loaded through XML.
             inline bool isLoadable() const { return this->bLoadable_; }
-            /** @brief Set the class to be loadable through XML or not. */
+            /// Set the class to be loadable through XML or not.
             inline void setLoadable(bool bLoadable) { this->bLoadable_ = bLoadable; }
 
@@ -133 +153 @@
             static void createClassHierarchy();
 
-            /** @brief Returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents. @return The status of the class-hierarchy creation */
+            /// Returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents.
             inline static bool isCreatingHierarchy() { return (hierarchyCreatingCounter_s > 0); }
 
-            /** @brief Returns the parents of the class the Identifier belongs to. @return The list of all parents */
+            /// Returns the parents of the class the Identifier belongs to.
             inline const std::set<const Identifier*>& getParents() const { return this->parents_; }
-            /** @brief Returns the begin-iterator of the parents-list. @return The begin-iterator */
+            /// Returns the begin-iterator of the parents-list.
             inline std::set<const Identifier*>::const_iterator getParentsBegin() const { return this->parents_.begin(); }
-            /** @brief Returns the end-iterator of the parents-list. @return The end-iterator */
+            /// Returns the end-iterator of the parents-list.
             inline std::set<const Identifier*>::const_iterator getParentsEnd() const { return this->parents_.end(); }
 
-            /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
+            /// Returns the children of the class the Identifier belongs to.
             inline const std::set<const Identifier*>& getChildren() const { return this->children_; }
-            /** @brief Returns the begin-iterator of the children-list. @return The begin-iterator */
+            /// Returns the begin-iterator of the children-list.
             inline std::set<const Identifier*>::const_iterator getChildrenBegin() const { return this->children_.begin(); }
-            /** @brief Returns the end-iterator of the children-list. @return The end-iterator */
+            /// Returns the end-iterator of the children-list.
             inline std::set<const Identifier*>::const_iterator getChildrenEnd() const { return this->children_.end(); }
 
-            /** @brief Returns the direct parents of the class the Identifier belongs to. @return The list of all direct parents */
+            /// Returns the direct parents of the class the Identifier belongs to.
             inline const std::set<const Identifier*>& getDirectParents() const { return this->directParents_; }
-            /** @brief Returns the begin-iterator of the direct-parents-list. @return The begin-iterator */
+            /// Returns the begin-iterator of the direct-parents-list.
             inline std::set<const Identifier*>::const_iterator getDirectParentsBegin() const { return this->directParents_.begin(); }
-            /** @brief Returns the end-iterator of the direct-parents-list. @return The end-iterator */
+            /// Returns the end-iterator of the direct-parents-list.
             inline std::set<const Identifier*>::const_iterator getDirectParentsEnd() const { return this->directParents_.end(); }
 
-            /** @brief Returns the direct children the class the Identifier belongs to. @return The list of all direct children */
+            /// Returns the direct children the class the Identifier belongs to.
             inline const std::set<const Identifier*>& getDirectChildren() const { return this->directChildren_; }
-            /** @brief Returns the begin-iterator of the direct-children-list. @return The begin-iterator */
+            /// Returns the begin-iterator of the direct-children-list.
             inline std::set<const Identifier*>::const_iterator getDirectChildrenBegin() const { return this->directChildren_.begin(); }
-            /** @brief Returns the end-iterator of the direct-children-list. @return The end-iterator */
+            /// Returns the end-iterator of the direct-children-list.
             inline std::set<const Identifier*>::const_iterator getDirectChildrenEnd() const { return this->directChildren_.end(); }
 
@@ -176 +196 @@
             static void clearNetworkIDs();
 
-            /** @brief Returns the map that stores all Identifiers with their names. @return The map */
+            /// Returns the map that stores all Identifiers with their names.
             static inline const std::map<std::string, Identifier*>& getStringIdentifierMap() { return Identifier::getStringIdentifierMapIntern(); }
-            /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names. @return The const_iterator */
+            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names.
             static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapBegin() { return Identifier::getStringIdentifierMap().begin(); }
-            /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names. @return The const_iterator */
+            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names.
             static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapEnd() { return Identifier::getStringIdentifierMap().end(); }
 
-            /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
+            /// Returns the map that stores all Identifiers with their names in lowercase.
             static inline const std::map<std::string, Identifier*>& getLowercaseStringIdentifierMap() { return Identifier::getLowercaseStringIdentifierMapIntern(); }
-            /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
+            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase.
             static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapBegin() { return Identifier::getLowercaseStringIdentifierMap().begin(); }
-            /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
+            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase.
             static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapEnd() { return Identifier::getLowercaseStringIdentifierMap().end(); }
 
-            /** @brief Returns the map that stores all Identifiers with their IDs. @return The map */
+            /// Returns the map that stores all Identifiers with their IDs.
             static inline const std::map<uint32_t, Identifier*>& getIDIdentifierMap() { return Identifier::getIDIdentifierMapIntern(); }
-            /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs. @return The const_iterator */
+            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs.
             static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapBegin() { return Identifier::getIDIdentifierMap().begin(); }
-            /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their IDs. @return The const_iterator */
+            /// Returns a const_iterator to the end of the map that stores all Identifiers with their IDs.
             static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapEnd() { return Identifier::getIDIdentifierMap().end(); }
 
@@ -203 +223 @@
             virtual void updateConfigValues(bool updateChildren = true) const = 0;
 
-            /** @brief Returns true if this class has at least one config value. @return True if this class has at least one config value */
+            /// Returns true if this class has at least one config value.
             inline bool hasConfigValues() const { return this->bHasConfigValues_; }
 
@@ -213 +233 @@
             ///// XMLPort /////
             ///////////////////
-            /** @brief Returns the map that stores all XMLPort params. @return The const_iterator */
+            /// Returns the map that stores all XMLPort params.
             inline const std::map<std::string, XMLPortParamContainer*>& getXMLPortParamMap() const { return this->xmlportParamContainers_; }
-            /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort params. @return The const_iterator */
+            /// Returns a const_iterator to the beginning of the map that stores all XMLPort params.
             inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapBegin() const { return this->xmlportParamContainers_.begin(); }
-            /** @brief Returns a const_iterator to the end of the map that stores all XMLPort params. @return The const_iterator */
+            /// Returns a const_iterator to the end of the map that stores all XMLPort params.
             inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapEnd() const { return this->xmlportParamContainers_.end(); }
 
-            /** @brief Returns the map that stores all XMLPort objects. @return The const_iterator */
+            /// Returns the map that stores all XMLPort objects.
             inline const std::map<std::string, XMLPortObjectContainer*>& getXMLPortObjectMap() const { return this->xmlportObjectContainers_; }
-            /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort objects. @return The const_iterator */
+            /// Returns a const_iterator to the beginning of the map that stores all XMLPort objects.
             inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapBegin() const { return this->xmlportObjectContainers_.begin(); }
-            /** @brief Returns a const_iterator to the end of the map that stores all XMLPort objects. @return The const_iterator */
+            /// Returns a const_iterator to the end of the map that stores all XMLPort objects.
             inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapEnd() const { return this->xmlportObjectContainers_.end(); }
 
@@ -244 +264 @@
             void initializeClassHierarchy(std::set<const Identifier*>* parents, bool bRootClass);
 
-            /** @brief Returns the map that stores all Identifiers with their names. @return The map */
+            /// Returns the map that stores all Identifiers with their names.
             static std::map<std::string, Identifier*>& getStringIdentifierMapIntern();
-            /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
+            /// Returns the map that stores all Identifiers with their names in lowercase.
             static std::map<std::string, Identifier*>& getLowercaseStringIdentifierMapIntern();
-            /** @brief Returns the map that stores all Identifiers with their network IDs. @return The map */
+            /// Returns the map that stores all Identifiers with their network IDs.
             static std::map<uint32_t, Identifier*>& getIDIdentifierMapIntern();
 
-            /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
+            /// Returns the children of the class the Identifier belongs to.
             inline std::set<const Identifier*>& getChildrenIntern() const { return this->children_; }
-            /** @brief Returns the direct children of the class the Identifier belongs to. @return The list of all direct children */
+            /// Returns the direct children of the class the Identifier belongs to.
             inline std::set<const Identifier*>& getDirectChildrenIntern() const { return this->directChildren_; }
 
@@ -259 +279 @@
 
         private:
-            /** @brief Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents. */
+            /// Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents.
             inline static void startCreatingHierarchy() { hierarchyCreatingCounter_s++; }
-            /** @brief Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents. */
+            /// Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents.
             inline static void stopCreatingHierarchy()  { hierarchyCreatingCounter_s--; }
 
@@ -297 +317 @@
     // ###     ClassIdentifier     ###
     // ###############################
-    //! The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
-    /**
-        ClassIdentifier is a Singleton, which means that only one object of a given type T exists.
+    /**
+        @brief The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
+
+        ClassIdentifier is a Singleton, which means that only one ClassIdentifier for a given type T exists.
         This makes it possible to store information about a class, sharing them with all
         objects of that class without defining static variables in every class.
 
         To be really sure that not more than exactly one object exists (even with libraries),
-        ClassIdentifiers are stored in the Identifier Singleton.
+        ClassIdentifiers are stored in a static map in Identifier.
     */
     template <class T>

code/branches/doc/src/libraries/core/Iterator.h

@@ -30 +30 @@
     @file
     @ingroup Object ObjectList
-    @brief Definition and implementation of the Iterator class.
-
-    The Iterator of a given class allows to iterate through an ObjectList. Objects in
-    this list are cast to the template argument of the Iterator.
+    @brief Definition of the Iterator class.
+
+    @anchor IteratorExample
+
+    @ref orxonox::Iterator "Iterator" allows to iterate through an @ref orxonox::ObjectListBase
+    "ObjectListBase". Objects in this list are cast to the template argument @a T of Iterator<T> using
+    @c dynamic_cast. In contrast to @ref orxonox::ObjectListIterator "ObjectListIterator<T>",
+    @ref orxonox::Iterator "Iterator<T>" can iterate through every object-list. In practice though it
+    is limited to objects of type @a T and its subclasses. Because of the @c dynamic_cast, this iterator
+    is much slower than ObjectListIterator.
 
     Usage:
+    @code
     for (Iterator<myClass> it = anyidentifier->getObjects()->begin(); it != anyidentifier->getObjects()->end(); ++it)
     {
@@ -41 +48 @@
         myClass* myObject = *it;
     }
+    @endcode
 */
 
@@ -53 +61 @@
 namespace orxonox
 {
-    //! The Iterator allows to iterate through a given ObjectList
+    /**
+        @brief The Iterator allows to iterate through a given ObjectList.
+
+        Independent of the object-list's type, the objects in the list are always casted
+        to @a T using @c dynamic_cast.
+
+        @see See @ref IteratorExample "Iterator.h" for more information an example.
+    */
     template <class T = OrxonoxClass>
     class Iterator

code/branches/doc/src/libraries/core/Language.h

@@ -35 +35 @@
     @file
     @ingroup Language
-    @brief Definition of the Language and the LanguageEntry class.
+    @brief Declaration of the Language and the LanguageEntry class, as well as some helper functions.
+
+    @anchor LanguageExample
 
     The Language class is used, to get a localisation of a string in the configured language.
@@ -43 +45 @@
     Usage:
      - Set the entry with the default string:
+       @code
        Language::getInstance()->addEntry("label of the entry", "the string to translate");
+       @endcode
 
      - Get the localisation of the entry in the configured language:
+       @code
        std::cout << Language::getInstance()->getLocalisation("name of the entry") << std::endl;
+       @endcode
+
+    Example:
+    @code
+    int age = 20;
+    AddLanguageEntry("user_age", "Age");
+    std::cout << GetLocalisation("user_age") << ": " << age << std::endl;
+    @endcode
+
+    Resulting output:
+    @code
+    Age: 20
+    @endcode
+
+    The language entry is now defined in @a translation_default.lang:
+    @code
+    user_age=Age
+    @endcode
+
+    We can add a translation for another language, for example @a translation_german.lang:
+    @code
+    user_age=Alter
+    @endcode
+
+    Now change the language in @a orxonox.ini to "german":
+    @code
+    language_ = "german"
+    @endcode
+
+    Now you will see the translated language entry in the resulting output of the above code:
+    @code
+    Alter: 20
+    @endcode
 */
 
@@ -64 +102 @@
     // ###      LanguageEntry      ###
     // ###############################
-    //! The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
+    /**
+        @brief The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
+
+        This class belongs to the Language class.
+    */
     class _CoreExport LanguageEntry
     {
@@ -111 +153 @@
     // ###         Language        ###
     // ###############################
-    //! The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
+    /**
+        @brief The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
+
+        @see See @ref LanguageExample "Language.h" for some examples.
+    */
     class _CoreExport Language : public Singleton<Language>
     {
@@ -140 +186 @@
     };
 
-    //! Shortcut function for Language::addEntry
+    /// Shortcut function for Language::addEntry
     inline void AddLanguageEntry(const LanguageEntryLabel& label, const std::string& fallbackString)
     {
@@ -146 +192 @@
     }
 
-    //! Shortcut function for Language::getLocalisation
+    /// Shortcut function for Language::getLocalisation
     inline const std::string& GetLocalisation(const LanguageEntryLabel& label)
     {
@@ -152 +198 @@
     }
 
-    //! Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
+    /// Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
     inline const std::string& GetLocalisation_noerror(const LanguageEntryLabel& label)
     {

code/branches/doc/src/libraries/core/MetaObjectList.h

@@ -30 +30 @@
     @file
     @ingroup Object ObjectList
-    @brief Definition of the MetaObjectList class.
+    @brief Declaration of the MetaObjectList class.
 
     The MetaObjectList is a single-linked list, containing all list-elements and their
@@ -47 +47 @@
     // ###  MetaObjectListElement  ###
     // ###############################
-    //! The list-element of the MetaObjectList
+    /// The list-element of the MetaObjectList
     class _CoreExport MetaObjectListElement
     {
@@ -66 +66 @@
     // ###     MetaObjectList      ###
     // ###############################
-    //!  The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
     /**
+        @brief The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
+
         The MetaObjectList is a single-linked list, containing all list-elements and their
         lists wherein the object that owns the MetaObjectList is registered.

code/branches/doc/src/libraries/core/ObjectList.h

@@ -35 +35 @@
     @file
     @ingroup Object ObjectList
-    @brief Definition and implementation of the ObjectList class.
+    @brief Definition of the ObjectList class.
 
-    The ObjectList is a wrapper of an ObjectListBase of a given class.
-    Use Iterator<class> to iterate through all objects of the class.
+    @ref orxonox::ObjectList "ObjectList<T>" is a wrapper of an @ref orxonox::ObjectListBase
+    "ObjectListBase" of class @a T. Use @ref orxonox::ObjectListIterator "ObjectListIterator<T>"
+    to iterate through the list.
 */
 
@@ -55 +56 @@
     // ###       ObjectList        ###
     // ###############################
-    //! The ObjectList contains all objects of the given class.
     /**
-        Wraps the ObjectListBase of the corresponding Identifier.
-        Use ObjectListIterator<class> to iterate through all objects in the list.
+        @brief The ObjectList contains all objects of the given class.
+
+        Wraps the ObjectListBase which contains all objects of type @a T. Use @ref ObjectListIterator
+        "ObjectListIterator<T>" or its typedef ObjectList<T>::iterator to iterate through all objects
+        in the list.
     */
     template <class T>
@@ -66 +69 @@
             typedef ObjectListIterator<T> iterator;
 
-            /** @brief Returns an Iterator to the first element in the list. @return The Iterator */
+            /// Returns an Iterator to the first element in the list.
             inline static ObjectListElement<T>* begin()
             {
@@ -73 +76 @@
             }
 
-            /** @brief Returns an Iterator to the element after the last element in the list. @return The Iterator */
+            /// Returns an Iterator to the element after the last element in the list.
             inline static ObjectListElement<T>* end()
             {
@@ -80 +83 @@
             }
 
-            /** @brief Returns an Iterator to the last element in the list. @return The Iterator */
+            /// Returns an Iterator to the last element in the list.
             inline static ObjectListElement<T>* rbegin()
             {
@@ -87 +90 @@
             }
 
-            /** @brief Returns an Iterator to the element before the first element in the list. @return The Iterator */
+            /// Returns an Iterator to the element before the first element in the list.
             inline static ObjectListElement<T>* rend()
             {

code/branches/doc/src/libraries/core/ObjectListBase.cc

@@ -30 +30 @@
     @file
     @brief Implementation of the ObjectListBase class.
-
-    The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
-    Newly created objects are added through the RegisterObject-macro in its constructor.
 */
 

code/branches/doc/src/libraries/core/ObjectListBase.h

@@ -30 +30 @@
     @file
     @ingroup Object ObjectList
-    @brief Definition of the ObjectListBase class.
+    @brief Declaration of the ObjectListBase class.
 
-    The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
-    Newly created objects are added through the RegisterObject-macro in its constructor.
+    orxonox::ObjectListBase is a double-linked list, used by @ref orxonox::Identifier "Identifiers"
+    to store all objects of a given class. Newly created objects are added to the list through the
+    @c RegisterObject() macro in the constructor.
 */
 
@@ -49 +50 @@
     // ###  ObjectListBaseElement  ###
     // ###############################
-    //! The list-element of the ObjectListBase
+    /// The list-element of the ObjectListBase
     class _CoreExport ObjectListBaseElement
     {
@@ -68 +69 @@
     // ###    ObjectListElement    ###
     // ###############################
-    //! The list-element that actually contains the object
+    /// The list-element that actually contains the object
     template <class T>
     class ObjectListElement : public ObjectListBaseElement
@@ -81 +82 @@
     // ###     ObjectListBase      ###
     // ###############################
-    //! The ObjectListBase contains all objects of a given class.
     /**
-        The ObjectListBase is used by Identifiers to store all objects of their given class.
-        Use ObjectList<T> to get the list of all T's and Iterator<T> to iterate through them.
+        @brief The ObjectListBase contains all objects of a given class.
+
+        The ObjectListBase is used by Identifiers to store all objects of their class.
+        You can use Identifier::getObjects() to get the object-list from an Identifier.
+        Use @ref Iterator "Iterator<T>" to iterate through them.
+
+        Alternatively you can also use the static helper class @ref orxonox::ObjectList "ObjectList<T>"
+        to get the list of all objects of type @a T. Use @ref ObjectListIterator "ObjectListIterator<T>"
+        or @ref Iterator "Iterator<T>" to iterate through them.
     */
     class _CoreExport ObjectListBase
@@ -96 +103 @@
             ObjectListBaseElement* add(ObjectListBaseElement* element);
 
+            /// Helper struct, used to export an element and the list to an instance of Iterator.
             struct Export
             {
@@ -103 +111 @@
             };
 
-            /** @brief Returns a pointer to the first element in the list. @return The element */
+            /// Returns a pointer to the first element in the list. Works only with Iterator.
             inline Export begin() { return ObjectListBase::Export(this, this->first_); }
-            /** @brief Returns a pointer to the element after the last element in the list. @return The element */
+            /// Returns a pointer to the element after the last element in the list. Works only with Iterator.
             inline Export end() { return ObjectListBase::Export(this, 0); }
-            /** @brief Returns a pointer to the last element in the list. @return The element */
+            /// Returns a pointer to the last element in the list. Works only with Iterator.
             inline Export rbegin() { return ObjectListBase::Export(this, this->last_); }
-            /** @brief Returns a pointer to the element in front of the first element in the list. @return The element */
+            /// Returns a pointer to the element in front of the first element in the list. Works only with Iterator.
             inline Export rend() { return ObjectListBase::Export(this, 0); }
 

code/branches/doc/src/libraries/core/ObjectListIterator.h

@@ -30 +30 @@
     @file
     @ingroup Object ObjectList
-    @brief Definition and implementation of the Iterator class.
-
-    The ObjectListIterator of a given class allows to iterate through the
-    ObjectList of this class, containing all objects of that type.
-    This is the only way to access the objects stored in an ObjectList.
+    @brief Definition of the ObjectListIterator class.
+
+    @anchor ObjectListIteratorExample
+
+    @ref orxonox::ObjectListIterator "ObjectListIterator<T>" allows to iterate through
+    @ref orxonox::ObjectList "ObjectList<T>", containing all objects of type @a T. In contrast to
+    @ref orxonox::Iterator "Iterator<T>", this iterator is limited to the object-list of type @a T.
+    It is, however, much faster as it doesn't need a @c dynamic_cast.
 
     Usage:
+    @code
     for (ObjectListIterator<myClass> it = ObjectList<myClass>::begin(); it != ObjectList<myClass>::end(); ++it)
     {
@@ -42 +46 @@
         myClass* myObject = *it;
     }
+    @endcode
+
+    @note @ref orxonox::ObjectList::iterator "ObjectList<T>::iterator" is identical to
+          @ref orxonox::ObjectListIterator "ObjectListIterator<T>" (it's just a typedef).
 */
 
@@ -53 +61 @@
 namespace orxonox
 {
-    //! The Iterator allows to iterate through the ObjectList of a given class.
+    /**
+        @brief ObjectListIterator<T> allows to iterate through the ObjectList of class @a T.
+
+        @see See @ref ObjectListIteratorExample "ObjectListIterator.h" for more information an example.
+    */
     template <class T>
     class ObjectListIterator
@@ -218 +230 @@
 
         private:
-            ObjectListElement<T>* element_;        //!< The element the Iterator points at
+            ObjectListElement<T>* element_;        //!< The element the iterator points at
     };
 }

code/branches/doc/src/libraries/core/OrxonoxClass.h

@@ -59 +59 @@
 namespace orxonox
 {
-    //! The class all objects and interfaces of the game-logic (not the engine) are derived from.
     /**
-        The BaseObject and Interfaces are derived with 'virtual public OrxonoxClass' from OrxonoxClass.
+        @brief The class all objects and interfaces of the game-logic (not the engine) are derived from.
+
+        The BaseObject and Interfaces are derived with @c virtual @c public @c OrxonoxClass from OrxonoxClass.
         OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the MetaObjectList.
     */
@@ -82 +83 @@
             void unregisterObject();
 
-            /** @brief Function to collect the SetConfigValue-macro calls. */
+            /// Function to collect the SetConfigValue-macro calls.
             void setConfigValues() {};
 
-            /** @brief Returns the Identifier of the object. @return The Identifier */
+            /// Returns the Identifier of the object.
             inline Identifier* getIdentifier() const { return this->identifier_; }
 
@@ -137 +138 @@
             }
 
-            //! Version of getDerivedPointer with template
+            /// Version of getDerivedPointer with template
             template <class T> FORCEINLINE T* getDerivedPointer(unsigned int classID)
             {   return static_cast<T*>(this->getDerivedPointer(classID));   }
-            //! Const version of getDerivedPointer with template
+            /// Const version of getDerivedPointer with template
             template <class T> FORCEINLINE const T* getDerivedPointer(unsigned int classID) const
             {   return const_cast<OrxonoxClass*>(this)->getDerivedPointer<T>(classID);   }
@@ -148 +149 @@
 
         private:
-            /** @brief Increments the reference counter (for smart pointers). */
+            /// Increments the reference counter (for smart pointers).
             inline void incrementReferenceCount()
                 { ++this->referenceCount_; }
-            /** @brief Decrements the reference counter (for smart pointers). */
+            /// Decrements the reference counter (for smart pointers).
             inline void decrementReferenceCount()
             {
@@ -159 +160 @@
             }
 
-            /** @brief Register a weak pointer which points to this object. */
+            /// Register a weak pointer which points to this object.
             template <class T>
             inline void registerWeakPtr(WeakPtr<T>* pointer)
                 { this->weakPointers_.insert(reinterpret_cast<WeakPtr<OrxonoxClass>*>(pointer)); }
-            /** @brief Unegister a weak pointer which pointed to this object before. */
+            /// Unegister a weak pointer which pointed to this object before.
             template <class T>
             inline void unregisterWeakPtr(WeakPtr<T>* pointer)
@@ -175 +176 @@
             std::set<WeakPtr<OrxonoxClass>*> weakPointers_; //!< All weak pointers which point to this object (and like to get notified if it dies)
 
-            //! 'Fast map' that holds this-pointers of all derived types
+            /// 'Fast map' that holds this-pointers of all derived types
             std::vector<std::pair<unsigned int, void*> > objectPointers_;
     };

code/branches/doc/src/libraries/core/SubclassIdentifier.h

@@ -32 +32 @@
     @brief Definition of SubclassIdentifier.
 
+    @anchor SubclassIdentifierExample
+
     SubclassIdentifier is a separated class, acting like an Identifier, but has a given class.
     You can only assign Identifiers of exactly the given class or of a derivative to a SubclassIdentifier.
+
+    Example:
+
+    You can assign an Identifier either through the constructor or by using the assignment @c operator=:
+    @code
+    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
+    @endcode
+
+    The @c operator-> is overloaded an returns the assigned Identifier. That way you can just call
+    functions of the assigned Identifier by using @c ->function():
+    @code
+    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
+    identifier->getName();      // returns "SubClass"
+    @endcode
+
+    There are two possibilities to create an object out of a SubclassIdentifier: Either you just use
+    the @c fabricate() function of the assigned Identifier through the overloaded @c operator->, which
+    returns a @c BaseObject* pointer, or you use the function of SubclassIdentifier, this time by using
+    @c operator., which returns a @c BaseClass* pointer (@a BaseClass is the baseclass specified by the
+    template argument):
+    @code
+    identifier->fabricate();    // calls Identifier::fabricate(), creates a SubClass, returns a BaseObject* pointer
+
+    identifier.fabricate();     // calls SubclassIdentifier::fabricate(), creates a SubClass, returns a BaseClass* pointer
+    @endcode
 */
 
@@ -50 +77 @@
     // ###   SubclassIdentifier    ###
     // ###############################
-    //! The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
     /**
+        @brief The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
+
         You can only assign an Identifier that belongs to a class T (or derived) to a SubclassIdentifier<T>.
-        If you assign something else, the program aborts.
-        Because we know the minimum type, a dynamic_cast is done, which makes it easier to create a new object.
+        If you assign something else, the program prints an error.
+
+        Because we know the base-type, a @c dynamic_cast is done, which makes it easier to create a new object.
+
+        @see See @ref SubclassIdentifierExample "SubclassIdentifier.h" for some examples.
     */
     template <class T>
@@ -60 +91 @@
     {
         public:
-            /**
-                @brief Constructor: Automaticaly assigns the Identifier of the given class.
-            */
+            /// Constructor: Automaticaly assigns the Identifier of the given class.
             SubclassIdentifier()
             {
@@ -68 +97 @@
             }
 
-            /**
-                @brief Constructor: Assigns the given Identifier.
-                @param identifier The Identifier
-            */
+            /// Constructor: Assigns the given Identifier.
             SubclassIdentifier(Identifier* identifier)
             {
@@ -77 +103 @@
             }
 
-            /**
-                @brief Copyconstructor: Assigns the identifier of the other SubclassIdentifier.
-                @param identifier The other SublcassIdentifier
-            */
+            /// Copyconstructor: Assigns the identifier of another SubclassIdentifier.
             template <class O>
             SubclassIdentifier(const SubclassIdentifier<O>& identifier)
@@ -114 +137 @@
             }
 
-            /**
-                @brief Overloading of the = operator: assigns the identifier of the other SubclassIdentifier.
-                @param identifier The other SublcassIdentifier
-            */
+            /// Overloading of the = operator: assigns the identifier of another SubclassIdentifier.
             template <class O>
             SubclassIdentifier<T>& operator=(const SubclassIdentifier<O>& identifier)
@@ -124 +144 @@
             }
 
-            /**
-                @brief Overloading of the * operator: returns the assigned identifier.
-            */
+            /// Overloading of the * operator: returns the assigned identifier.
             inline Identifier* operator*() const
             {
@@ -132 +150 @@
             }
 
-            /**
-                @brief Overloading of the -> operator: returns the assigned identifier.
-            */
+            /// Overloading of the -> operator: returns the assigned identifier.
             inline Identifier* operator->() const
             {
@@ -140 +156 @@
             }
 
-            /**
-                @brief Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
-            */
+            /// Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
             inline operator Identifier*() const
             {
@@ -148 +162 @@
             }
 
-            /**
-                @brief Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
-                @return The new object
-            */
+            /// Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
             T* fabricate(BaseObject* creator) const
             {
@@ -182 +193 @@
             }
 
-            /** @brief Returns the assigned identifier. @return The identifier */
+            /// Returns the assigned identifier.
             inline Identifier* getIdentifier() const
                 { return this->identifier_; }

code/branches/doc/src/libraries/core/Super.h

@@ -37 +37 @@
     @brief Definition of all super-function related macros.
 
-    This file defines all macros needed to add a new "super-function".
-    If you add a super-function, you can call SUPER(myclass, functionname) inside your
-    code and the function of the parentclass gets called. This is comparable with
-    super.functionname() in Java or other languages.
-
-    This works only with virtual functions that return nothing (void) and belong to
-    classes that have an Identifier. Arguments however are supported.
-
-    To add a new super-function, you have process 4 steps:
-
-    1) Add a new SUPER macro
-       This allows you to call the super-function in your code.
-       Location: This file (Super.h), marked with --> HERE <-- comments (1/3)
-
-    2) Call the SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros.
-       This defines some global classes and templates, needed to create and call the super-functions.
-       Location: This file (Super.h), marked with --> HERE <-- comments (2/3)
-
-    3) Call the SUPER_INTRUSIVE_DECLARATION macro.
-       This will be included into the declaration of ClassIdentifier<T>.
-       Location: This file (Super.h), marked with --> HERE <-- comments (3/3)
-
-    4) Call the SUPER_FUNCTION macro.
+    This file defines all macros needed to add a new "super-function". If you add
+    a super-function, you can call <tt>SUPER(myclass, functionname, arguments)</tt>
+    inside your code and the function of the parent-class gets called. This is comparable
+    to <tt>super.functionname(arguments)</tt> in Java or other languages.
+
+    This works only with virtual functions that return nothing (@c void) and belong to
+    classes that have an @ref orxonox::Identifier "Identifier". Arguments however are
+    supported, there's no limitation for their number and type, except that the type has
+    to be known in Super.h.
+
+    To add a new super-function, you have to process 4 steps:
+
+    -# Add a new @c SUPER macro <br />
+       This allows you to call the super-function in your code. <br />
+       Location: This file (Super.h), marked with "--> HERE <--" comments (1/3)
+    -# Call the @c SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros. <br />
+       This defines some global classes and templates, needed to create and call the super-functions. <br />
+       Location: This file (Super.h), marked with "--> HERE <--" comments (2/3)
+    -# Call the @c SUPER_INTRUSIVE_DECLARATION macro. <br />
+       This will be included into the declaration of @c ClassIdentifier<T>. <br />
+       Location: This file (Super.h), marked with "--> HERE <--" comments (3/3)
+    -# Call the @c SUPER_FUNCTION macro. <br />
        This defines a partially specialized template that will decide if a class is "super" to another class.
-       If the check returns true, a SuperFunctionCaller gets created, which will be used by the SUPER macro.
+       If the check returns true, a @c SuperFunctionCaller gets created, which will be used by the @c SUPER macro.
        You have to add this into the header-file of the baseclass of the super-function (the class that first
        implements the function), below the class declaration. You can't call it directly in this file, because
-       otherwise you had to include the headerfile right here, which would cause some ugly backdependencies,
-       include loops and slower compilation.
-       Dont forget to include Super.h in the header-file.
+       otherwise you had to include the headerfile right here, which would cause some ugly back-dependencies,
+       include loops and slower compilation. <br />
+       Dont forget to include Super.h in the header-file. <br />
        Location: The header-file of the baseclass (Baseclass.h), below the class declaration
 */
@@ -211 +210 @@
     */
 
-    // SUPER-macro: Calls Parent::functionname() where Parent is the direct parent of classname
+    /// SUPER-macro: Calls Parent::functionname(...) where Parent is the direct parent of @a classname
     #ifdef ORXONOX_COMPILER_MSVC
         #define SUPER(classname, functionname, ...) \