Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changeset 7372 for code/branches/doc/src


Ignore:
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:
23 edited

Legend:

Unmodified
Added
Removed
  • code/branches/doc/src/libraries/core/BaseObject.h

    r7363 r7372  
    5959    class Level;
    6060
    61     //! The BaseObject is the parent of all classes representing an instance in the game.
     61    /// The BaseObject is the parent of all classes representing an instance in the game.
    6262    class _CoreExport BaseObject : virtual public OrxonoxClass
    6363    {
  • code/branches/doc/src/libraries/core/ClassFactory.h

    r7363 r7372  
    5050    // ###       Factory       ###
    5151    // ###########################
    52     //! Base-class of ClassFactory.
     52    /// Base-class of ClassFactory.
    5353    class _CoreExport Factory
    5454    {
     
    6161    // ###      ClassFactory       ###
    6262    // ###############################
    63     //! The ClassFactory is able to create new objects of a specific class.
     63    /// The ClassFactory is able to create new objects of a specific class.
    6464    template <class T>
    6565    class ClassFactory : public Factory
  • code/branches/doc/src/libraries/core/ClassTreeMask.cc

    r7268 r7372  
    2929/**
    3030    @file
    31     @brief Implementation of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
     31    @brief Implementation of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
    3232*/
    3333
     
    9393    /**
    9494        @brief Adds a new subnode to the list of subnodes.
    95         @param subnode The new subnode
    9695    */
    9796    void ClassTreeMaskNode::addSubnode(ClassTreeMaskNode* subnode)
     
    178177    /**
    179178        @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
    180         @return The pointer to the node
    181179    */
    182180    ClassTreeMaskNode* ClassTreeMaskIterator::operator*() const
     
    187185    /**
    188186        @brief Returns a pointer to the ClassTreeMaskNode whereon the iterator points.
    189         @return The pointer to the node
    190187    */
    191188    ClassTreeMaskNode* ClassTreeMaskIterator::operator->() const
     
    196193    /**
    197194        @brief Returns true if the stack is empty, meaning we've reached the end of the tree.
    198         @return True if we've reached the end of the tree
    199195    */
    200196    ClassTreeMaskIterator::operator bool() const
     
    205201    /**
    206202        @brief Compares the current node with the given one and returns true if they match.
    207         @param compare The node to compare with
    208         @return The result of the comparison (true if they match)
    209203    */
    210204    bool ClassTreeMaskIterator::operator==(ClassTreeMaskNode* compare) const
     
    218212    /**
    219213        @brief Compares the current node with the given one and returns true if they don't match.
    220         @param compare The node to compare with
    221         @return The result of the comparison (true if they don't match)
    222214    */
    223215    bool ClassTreeMaskIterator::operator!=(ClassTreeMaskNode* compare) const
     
    242234
    243235    /**
    244         @brief Copyconstructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
    245         @param other The other mask
     236        @brief Copy-constructor: Adds the root-node of the tree with the first rule ("include everything") and adds all rules from the other mask.
    246237    */
    247238    ClassTreeMask::ClassTreeMask(const ClassTreeMask& other)
  • code/branches/doc/src/libraries/core/ClassTreeMask.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Class
    32     @brief Definition of the ClassTreeMask, ClassTreeMaskNode and ClassTreeMaskIterator classes.
    33 
    34     ClassTreeMask is a class to define a mask of the class-tree beginning with BaseObject.
     32    @brief Declaration of the ClassTreeMask, ClassTreeMaskNode, and ClassTreeMaskIterator classes.
     33
     34    ClassTreeMask is a class to define a mask of the class-tree beginning with orxonox::BaseObject.
    3535    You can include or exclude classes by calling the corresponding functions with the
    36     Identifier of the class.
     36    orxonox::Identifier of the class. This mask can then be used to filter out objects that
     37    are instances of classes which aren't included in the tree, for example when Loading a
     38    level file or if a Trigger should be triggered by only a few classes.
     39
     40    See the description of orxonox::ClassTreeMask for a short example.
    3741
    3842    You can work with a ClassTreeMask in the sense of the set-theory, meaning that you can create
    3943    unions, intersections, complements and differences by using overloaded operators.
    4044
    41 
     45    @par Tree structure
    4246
    4347    The ClassTreeMask is internally represented by a tree. The nodes in the tree are
     
    4650    nodes changing the mask. By adding new rules, the tree gets reordered dynamically.
    4751
    48     Adding a new rule overwrites all rules assigned to inherited classes. Use overwrite = false
     52    Adding a new rule overwrites all rules assigned to inherited classes. Use <tt>overwrite = false</tt>
    4953    if you don't like this feature. Useless rules that don't change the information of the mask
    50     aren't saved in the internal tree. Use clean = false if you wan't to save them.
    51 
    52     With overwrite = false and clean = false it doesn't matter in which way you create the mask.
    53     You can manually drop useless rules from the tree by calling clean().
    54 
    55 
    56 
    57     Because of the complicated shape of the internal tree, there is an iterator to iterate
    58     through all ClassTreeMaskNodes of a mask. It starts with the BaseObject and moves on to
    59     the first subclass until it reaches a leaf of the tree. Then the iterator moves one step
    60     back and iterates to the second subclass. If there are no more subclasses, it steps another
    61     step back, and so on.
    62 
    63     Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
    64     The ClassTreeMaskIterator would move trough the tree in the following order:
    65     BaseObject, A, A1, A2, B, B1, B2.
    66 
    67     Note that the iterator doesn't move trough the whole class-tree, but only through the
    68     internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
     54    aren't saved in the internal tree. Use <tt>clean = false</tt> if you still want to save them.
     55
     56    With <tt>overwrite = false</tt> and <tt>clean = false</tt> it doesn't matter in which order
     57    you create the mask. You can manually drop useless rules from the tree by calling
     58    @ref orxonox::ClassTreeMask::clean() "clean()".
     59
     60    @par Objects
     61
     62    To iterate through all objects of the classes that were included by a ClassTreeMask,
     63    use orxonox::ClassTreeMaskObjectIterator. The description of this class also contains
     64    a short example of how to use it.
    6965*/
    7066
     
    8480    // ###      ClassTreeMaskNode      ###
    8581    // ###################################
    86     //! The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
    8782    /**
     83        @brief The ClassTreeMaskNode is a node in the internal tree of the ClassTreeMask, containing the rules of the mask.
     84
    8885        The ClassTreeMaskNode is used to store the rule (included or excluded) for a given
    8986        class (described by the corresponding Identifier). The nodes are used in the internal
     
    106103            void addSubnode(ClassTreeMaskNode* subnode);
    107104
    108             /** @brief Tells if the rule is "included" or not. @return The rule: true = included, false = excluded */
     105            /// Tells if the rule is "included" or not.
    109106            inline bool isIncluded() const { return this->bIncluded_; }
    110             /** @brief Tells if the rule is "excluded" or not. @return The inverted rule: true = excluded, false = included */
     107            /// Tells if the rule is "excluded" or not.
    111108            inline bool isExcluded() const { return (!this->bIncluded_); }
    112109
    113             /** @brief Returns the Identifier of the class the rule refers to. @return The Identifier representing the class */
     110            /// Returns the Identifier of the class the rule refers to.
    114111            inline const Identifier* getClass() const { return this->subclass_; }
    115112
    116             /** @brief Returns true if the Node has some subnodes. */
     113            /// Returns true if the node has some subnodes.
    117114            inline bool hasSubnodes() const { return !this->subnodes_.empty(); }
    118115
     
    120117            void deleteAllSubnodes();
    121118
    122             const Identifier* subclass_;                //!< The Identifier of the subclass the rule refers to
    123             bool bIncluded_;                            //!< The rule: included or excluded
    124             std::list<ClassTreeMaskNode*> subnodes_;    //!< A list containing all subnodes in the tree
     119            const Identifier* subclass_;                ///< The Identifier of the subclass the rule refers to
     120            bool bIncluded_;                            ///< The rule: included or excluded
     121            std::list<ClassTreeMaskNode*> subnodes_;    ///< A list containing all subnodes of this node
    125122    };
    126123
     
    129126    // ###    ClassTreeMaskIterator    ###
    130127    // ###################################
    131     //! The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask, containing the rules.
    132128    /**
     129        @brief The ClassTreeMaskIterator moves through all ClassTreeMaskNodes of the internal tree of a ClassTreeMask which contains the rules.
     130
    133131        Because of the complicated shape of the internal rule-tree of ClassTreeMask, an
    134132        iterator is used to move through all nodes of the tree. It starts with the BaseObject
     
    136134        iterator moves one step back and iterates to the second subclass. If there are no more
    137135        subclasses, it steps another step back, and so on.
     136
     137        Example: A and B are children of BaseObject, A1 and A2 are children of A, B1 and B2 are children of B.
     138        The ClassTreeMaskIterator would move trough the tree in the following order:
     139        BaseObject, A, A1, A2, B, B1, B2.
     140
     141        Note that the iterator doesn't move trough the whole class-tree, but only through the
     142        internal tree of the mask, containing the minimal needed set of nodes to describe the mask.
    138143    */
    139144    class _CoreExport ClassTreeMaskIterator
     
    151156
    152157        private:
    153             std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    //!< A stack to store list-iterators
    154             std::list<ClassTreeMaskNode*> rootlist_;                                                                            //!< A list for internal use (it only stores the root-node)
     158            std::stack<std::pair<std::list<ClassTreeMaskNode*>::iterator, std::list<ClassTreeMaskNode*>::iterator> > nodes_;    ///< A stack to store list-iterators
     159            std::list<ClassTreeMaskNode*> rootlist_;                                                                            ///< A list for internal use (it only stores the root-node)
    155160    };
    156161
     
    159164    // ###        ClassTreeMask        ###
    160165    // ###################################
    161     //! The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
    162166    /**
     167        @brief The ClassTreeMask is a set of rules, containing the information for each class whether it's included or not.
     168
    163169        With a ClassTreeMask, you can include or exclude subtrees of the class-tree, starting
    164170        with a given subclass, described by the corresponding Identifier. To minimize the size
    165171        of the mask, the mask saves only relevant rules. But you can manually add rules that
    166         don't change the information of the mask by using clean = false. If you want to drop
     172        don't change the information of the mask by using <tt>clean = false</tt>. If you want to drop
    167173        useless rules, call the clean() function.
     174
     175        Example:
     176        @code
     177        ClassTreeMask mymask;
     178        mymask.exclude(Class(A));
     179        mymask.exclude(Class(B));
     180        mymask.include(Class(ChildOfA));
     181        @endcode
     182
     183        In this example, the classes A and B are excluded from the mask, but one of the child
     184        classes of A is included again.
    168185    */
    169186    class _CoreExport ClassTreeMask
     
    190207            bool isExcluded(const Identifier* subclass) const;
    191208
    192             /** @brief Begin of the ClassTreeMaskObjectIterator. */
     209            /// Begin of the ClassTreeMaskObjectIterator.
    193210            inline const ClassTreeMask& begin() const { return (*this); }
    194             /** @brief End of the ClassTreeMaskObjectIterator. */
     211            /// End of the ClassTreeMaskObjectIterator.
    195212            inline BaseObject*          end()   const { return 0; }
    196213
     
    229246            bool nodeExists(const Identifier* subclass);
    230247
    231             ClassTreeMaskNode* root_;   //!< The root-node of the internal rule-tree, usually BaseObject
     248            ClassTreeMaskNode* root_;   ///< The root-node of the internal rule-tree, usually BaseObject
    232249    };
    233250
     
    236253    // ### ClassTreeMaskObjectIterator ###
    237254    // ###################################
    238     //! The ClassTreeMaskObjectIterator iterates through all objects of all classes, included by a ClassTreeMask.
    239255    /**
    240         The ClassTreeMaskObjectIterator iterates through all objects of all classes,
    241         included by a ClassTreeMask. This is done the following way:
    242 
     256        @brief The ClassTreeMaskObjectIterator iterates through all objects of the classes that were included by a ClassTreeMask.
     257
     258        This is done the following way:
     259        @code
    243260        ClassTreeMask mask;
    244261        for (ClassTreeMaskObjectIterator it = mask.begin(); it != mask.end(); ++it)
    245262            it->doSomething();
    246 
    247         Note: The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
     263        @endcode
     264
     265        @note The ClassTreeMaskObjectIterator handles all objects as BaseObjects. If
    248266              you want to use another class, you should use a dynamic_cast.
    249267
    250         Performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
     268        The performance of ClassTreeMaskObjectIterator is good as long as you don't exclude
    251269        subclasses of included classes. Of course you can still exlucde subclasses, but
    252270        if this is done more often, we need a new implementation using a second ObjectList
     
    256274    {
    257275        public:
    258             /** @brief Defaultconstructor: Does nothing. */
     276            /// Default-constructor: Does nothing.
    259277            inline ClassTreeMaskObjectIterator() {}
    260             /** @brief Constructor: Initializes the iterator from a given ClassTreeMask. @param mask The mask */
     278            /// Copy-Constructor: Initializes the iterator from another ClassTreeMask.
    261279            inline ClassTreeMaskObjectIterator(const ClassTreeMask& mask) { (*this) = mask; }
    262280
     
    265283            const ClassTreeMaskObjectIterator& operator++();
    266284
    267             /** @brief Returns true if the ClassTreeMaskObjectIterator points at the given object. @param pointer The pointer of the object */
     285            /// Returns true if the ClassTreeMaskObjectIterator points at the given object.
    268286            inline bool operator==(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) == pointer) || (!this->objectIterator_ && pointer == 0); }
    269             /** @brief Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object. @param pointer The pointer of the object */
     287            /// Returns true if the ClassTreeMaskObjectIterator doesn't point at the given object.
    270288            inline bool operator!=(BaseObject* pointer) const { return (this->objectIterator_ && (*this->objectIterator_) != pointer) || (!this->objectIterator_ && pointer != 0); }
    271             /** @brief Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end. */
     289            /// Returns true if the ClassTreeMaskObjectIterator hasn't already reached the end.
    272290            inline operator bool() const { return (this->objectIterator_); }
    273             /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
     291            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
    274292            inline BaseObject* operator*() const { return (*this->objectIterator_); }
    275             /** @brief Returns the object the ClassTreeMaskObjectIterator currently points at. */
     293            /// Returns the object the ClassTreeMaskObjectIterator currently points at.
    276294            inline BaseObject* operator->() const { return (*this->objectIterator_); }
    277295
     
    279297            void create(ClassTreeMaskNode* node);
    280298
    281             std::list<std::pair<const Identifier*, bool> >           subclasses_;       //!< A list of all Identifiers through which objects the iterator should iterate
    282             std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; //!< The current class of the iterator
    283             Iterator<BaseObject>                                     objectIterator_;   //!< The current object of the iterator
     299            std::list<std::pair<const Identifier*, bool> >           subclasses_;       ///< A list of all Identifiers through which objects the iterator should iterate
     300            std::list<std::pair<const Identifier*, bool> >::iterator subclassIterator_; ///< The current class of the iterator
     301            Iterator<BaseObject>                                     objectIterator_;   ///< The current object of the iterator
    284302    };
    285303}
  • code/branches/doc/src/libraries/core/CommandLineParser.h

    r7363 r7372  
    3636    @file
    3737    @ingroup Config CmdArgs
     38    @brief Declaration of CommandLineParser and CommandLineArgument, definition of the SetCommandLineArgument() macros.
    3839*/
    3940
  • code/branches/doc/src/libraries/core/ConfigValueContainer.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Config ConfigFile
    32     @brief Definition of the ConfigValueContainer class.
     32    @brief Declaration of the ConfigValueContainer class.
    3333
    3434    The ConfigValueContainer class contains all needed information about a configurable variable:
     
    7979
    8080
    81     //! The ConfigValuecontainer contains all needed information about a configurable variable.
    8281    /**
     82        @brief The ConfigValuecontainer contains all needed information about a configurable variable.
     83
    8384        The ConfigValueContainer class contains all needed information about a configurable variable:
    8485         - the name of the variable
     
    216217            }
    217218
    218             /** @brief Returns the name of this container. */
     219            /// Returns the name of this container.
    219220            inline const std::string& getName() const
    220221                { return this->varname_; }
    221             /** @brief Returns the name of the section this config value is in. */
     222            /// Returns the name of the section this config value is in.
    222223            inline const std::string& getSectionName() const
    223224                { return this->sectionname_; }
    224             /** @brief Returns the associated identifier (can be NULL). */
     225            /// Returns the associated identifier (can be NULL).
    225226            inline Identifier* getIdentifier() const
    226227                { return this->identifier_; }
    227             /** @brief Returns true if this config-value is a vector */
     228            /// Returns true if this config-value is a vector.
    228229            inline bool isVector() const
    229230                { return this->bIsVector_; }
    230             /** @brief Returns the vectors size (or zero if it's not a vector). */
     231            /// Returns the vectors size (or zero if it's not a vector).
    231232            inline unsigned int getVectorSize() const
    232233                { return this->valueVector_.size(); }
     
    268269            void update();
    269270
    270             /** @brief Converts the config-value to a string. @return The string */
     271            /// Converts the config-value to a string.
    271272            inline std::string toString() const
    272273                { return this->value_; }
    273             /** @brief Returns the typename of the assigned config-value. @return The typename */
     274            /// Returns the typename of the assigned config-value.
    274275            inline std::string getTypename() const
    275276                { return this->value_.getTypename(); }
  • code/branches/doc/src/libraries/core/ConfigValueIncludes.h

    r7363 r7372  
    3333
    3434/**
    35 @file
    36 @ingroup Config ConfigFile
    37 @brief
    38     Definition of macros and functions for config-values.
     35    @file
     36    @ingroup Config ConfigFile
     37    @brief Definition of macros and functions for config-values.
     38
     39    An example of how to use SetConfigValue():
     40
     41    Definition of a class in the header-file:
     42    @code
     43    class MyClass : public BaseObject
     44    {
     45        public:
     46            MyClass();              // Constructor
     47            void setConfigValues(); // Inherited function
     48
     49            const std::string& getName()
     50                { return this->name_; }
     51
     52            float getVersion()
     53                { return this->version_; }
     54
     55        private:
     56            std::string name_;
     57            float version_;
     58    };
     59    @endcode
     60
     61    Implementation of the class source-file:
     62    @code
     63    MyClass::MyClass()
     64    {
     65        // Macro-call to create an Identifier
     66        RegisterObject(MyClass);
     67
     68        // Function-call to assign the config-values to the new object
     69        this->setConfigValues();
     70    }
     71
     72    void MyClass::setConfigValues()
     73    {
     74        SetConfigValue(name_, "Orxonox").description("The name of the game");
     75        SetConfigValue(version_, "1.0").description("The version-number");
     76    }
     77    @endcode
     78
     79    Extract of orxonox.ini:
     80    @code
     81    [MyClass]
     82    name_ = "Orxonox"
     83    version_ = 1.1 // We have changed this value from 1.0 to 1.1
     84    @endcode
     85
     86    Some other code:
     87    @code
     88    MyObject orxonoxobject;
     89    std::cout << "Name:    " << orxonoxobject.getName() << std::endl;
     90    std::cout << "Version: " << orxonoxobject.getVersion() << std::endl;
     91    @endcode
     92
     93    Output:
     94    @code
     95    Name:    Orxonox
     96    Version: 1.1
     97    @endcode
    3998*/
    4099
  • code/branches/doc/src/libraries/core/CoreIncludes.h

    r7363 r7372  
    3737    @brief Definition of macros for Identifiers
    3838
    39     Every class needs the RegisterObject(class) macro in its constructor. If the class is an interface
    40     or the BaseObject itself, it needs the macro RegisterRootObject(class) instead.
     39    Every class needs the @c RegisterObject(class) macro in its constructor. If the class is an interface
     40    or the @c BaseObject itself, it needs the macro @c RegisterRootObject(class) instead.
    4141
    42     To allow the object being created through the factory, use the CreateFactory(class) macro outside
    43     the of the class implementation, so it gets executed before main().
     42    To allow the object being created through the factory, use the @c CreateFactory(class) macro outside
     43    of the class implementation, so it gets executed statically before @c main(). This will at the same time
     44    register @a class in the class-hierarchy. If you don't want @a class to be loadable, but still
     45    register it, call @c CreateUnloadableFactory(class).
     46
     47    Example:
     48    @code
     49    // Create the factory for MyClass
     50    CreateFactory(MyClass);
     51
     52    // Constructor:
     53    MyClass::MyClass()
     54    {
     55        // Register the object in the Identifier of MyClass
     56        RegisterObject(MyClass);
     57    }
     58    @endcode
     59
     60    This file also defines a number of other useful macros, like, for example, @c Class(class) which
     61    returns the @ref orxonox::Identifier "Identifier" of @a class, or @c ClassByString("class") which
     62    returns the Identifier of a class with name @a "class".
     63
     64    Example:
     65    @code
     66    // Assigns the Identifier of MyClass
     67    Identifier* identifier = Class(MyClass);
     68    @endcode
     69    @code
     70    // Assigns the Identifier of a class named "MyClass"
     71    Identifier* identifier = ClassByString("MyClass");
     72    @endcode
    4473*/
    4574
     
    5786
    5887/**
    59     @brief Intern macro, containing the common parts of RegisterObject and RegisterRootObject.
     88    @brief Intern macro, containing the common parts of @c RegisterObject and @c RegisterRootObject.
    6089    @param ClassName The name of the class
    61     @param bRootClass True if the class is directly derived from OrxonoxClass
     90    @param bRootClass True if the class is directly derived from orxonox::OrxonoxClass
    6291*/
    6392#define InternRegisterObject(ClassName, bRootClass) \
     
    6897
    6998/**
    70     @brief RegisterObject - with and without debug output.
     99    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
    71100    @param ClassName The name of the class
    72101*/
     
    75104
    76105/**
    77     @brief RegisterRootObject - with and without debug output.
     106    @brief Registers a newly created object in the core. Has to be called at the beginning of the constructor of @a ClassName.
    78107    @param ClassName The name of the class
     108
     109    In contrast to RegisterObject, this is used for classes that inherit directly from
     110    orxonox::OrxonoxClass, namely all interfaces and orxonox::BaseObject.
    79111*/
    80112#define RegisterRootObject(ClassName) \
  • code/branches/doc/src/libraries/core/Event.cc

    r7284 r7372  
    2626 *
    2727 */
     28
     29/**
     30    @file
     31    @brief Implementation of the classes Event and EventState.
     32*/
    2833
    2934#include "Event.h"
  • code/branches/doc/src/libraries/core/Event.h

    r7363 r7372  
    3535    @file
    3636    @ingroup Event
     37    @brief Declaration of the classes Event and EventState.
    3738*/
    3839
     
    6465        An event state is a state of an object, which can be changed by events.
    6566        Event states are changed through functions. Possible functions headers for set event states are:
    66          - memoryless state: function()
    67          - boolean state:    function(bool state)
    68          - individual state: function(bool state, SomeClass originator)
     67         - memoryless state: <tt>function()</tt>
     68         - boolean state:    <tt>function(bool state)</tt>
     69         - individual state: <tt>function(bool state, SomeClass originator)</tt>
    6970
    7071        Note that SomeClass may be any class deriving from BaseObject. You will not receive events from originators of other classes.
    71         The actual class for SomeClass must be specified as the second argument of the XMLPortEventState macro.
     72        The actual class for SomeClass must be specified as the second argument of the XMLPortEventState() macro.
    7273
    7374        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

    r7363 r7372  
    3030    @file
    3131    @ingroup Event
     32    @brief Definition of the XMLPortEventState() macro, as well as some more useful macros.
    3233*/
    3334
  • code/branches/doc/src/libraries/core/Identifier.cc

    r7284 r7372  
    217217    /**
    218218        @brief Sets the name of the class.
    219         @param name The name
    220219    */
    221220    void Identifier::setName(const std::string& name)
     
    253252    /**
    254253        @brief Sets the network ID to a new value and changes the entry in the ID-Identifier-map.
    255         @param id The new network ID
    256254    */
    257255    void Identifier::setNetworkID(uint32_t id)
  • code/branches/doc/src/libraries/core/Identifier.h

    r7363 r7372  
    3535    @file
    3636    @ingroup Class Identifier
    37     @brief Definition of the Identifier class, definition and implementation of the ClassIdentifier class.
    38 
    39     The Identifier contains all needed information about the class it belongs to:
    40      - the name
    41      - a list with all objects
    42      - parents and children
    43      - the factory (if available)
    44      - the networkID that can be synchronised with the server
    45      - all configurable variables (if available)
    46 
    47     Every object has a pointer to the Identifier of its class. This allows the use isA(...),
    48     isExactlyA(...), isChildOf(...) and isParentOf(...).
    49 
    50     To create the class-hierarchy, the Identifier has some intern functions and variables.
    51 
    52     Every Identifier is in fact a ClassIdentifier, but they are derived from Identifier.
     37    @brief Declaration of Identifier, definition of ClassIdentifier<T>.
     38
     39    @anchor IdentifierExample
     40
     41    An Identifier "identifies" the class of an object. It contains different information about
     42    the class: Its name and ID, a list of all instances of this class, a factory to create new
     43    instances of this class, and more.
     44
     45    It also contains information about the inheritance of this class: It stores a list of the
     46    Identifiers of all parent-classes as well as a list of all child-classes. These relationships
     47    can be tested using functions like @c isA(), @c isChildOf(), @c isParentOf(), and more.
     48
     49    Every Identifier is in fact a ClassIdentifier<T> (where T is the class that is identified
     50    by the Identifier), Identifier is just the common base-class.
     51
     52    Example:
     53    @code
     54    MyClass* object = new MyClass();                                            // create an instance of MyClass
     55
     56    object->getIdentifier()->getName();                                         // returns "MyClass"
     57
     58    BaseObject* other = object->getIdentifier()->fabricate(0);                  // fabricates a new instance of MyClass
     59
     60
     61    // iterate through all objects of type MyClass:
     62    ObjectListBase* objects = object->getIdentifier()->getObjects();            // get a pointer to the object-list
     63    int count;
     64    for (Iterator<BaseObject> it = objects.begin(); it != objects.end(); ++it)  // iterate through the objects
     65        ++count;
     66    COUT(0) << count << std::endl;                                              // prints "2" because we created 2 instances of MyClass so far
     67
     68
     69    // test the class hierarchy
     70    object->getIdentifier()->isA(Class(MyClass));                               // returns true
     71    object->isA(Class(MyClass));                                                // returns true (short version)
     72
     73    object->isA(Class(BaseClass));                                              // returns true if MyClass is a child of BaseClass
     74
     75    Class(ChildClass)->isChildOf(object->getIdentifier());                      // returns true if ChildClass is a child of MyClass
     76    @endcode
    5377*/
    5478
     
    76100    // ###       Identifier        ###
    77101    // ###############################
    78     //! The Identifier is used to identify the class of an object and to store information about the class.
    79     /**
    80         The Identifier contains all needed information about the class it belongs to:
    81          - the name
    82          - a list with all objects
    83          - parents and children
    84          - the factory (if available)
    85          - the networkID that can be synchronised with the server
    86          - all configurable variables (if available)
    87 
    88         Every object has a pointer to the Identifier of its class. This allows the use isA(...),
    89         isExactlyA(...), isChildOf(...) and isParentOf(...).
    90 
    91         You can't directly create an Identifier, it's just the base-class for ClassIdentifier.
     102    /**
     103        @brief The Identifier is used to identify the class of an object and to store information about the class.
     104
     105        Each Identifier stores information about one class. The Identifier can then be used to identify
     106        this class. On the other hand it's also possible to get the corresponding Identifier of a class,
     107        for example by using the macro Class().
     108
     109        @see See @ref IdentifierExample "Identifier.h" for more information and some examples.
     110
     111        @note You can't directly create an Identifier, it's just the base-class of ClassIdentifier<T>.
    92112    */
    93113    class _CoreExport Identifier
    94114    {
    95115        public:
    96             /** @brief Returns the name of the class the Identifier belongs to. @return The name */
     116            /// Returns the name of the class the Identifier belongs to.
    97117            inline const std::string& getName() const { return this->name_; }
    98118            void setName(const std::string& name);
    99119
    100             /** @brief Returns the network ID to identify a class through the network. @return the network ID */
     120            /// Returns the network ID to identify a class through the network.
    101121            inline const uint32_t getNetworkID() const { return this->networkID_; }
    102122            void setNetworkID(uint32_t id);
    103123
    104             /** @brief Returns the unique ID of the class */
     124            /// Returns the unique ID of the class.
    105125            FORCEINLINE unsigned int getClassID() const { return this->classID_; }
    106126
    107             /** @brief Returns the list of all existing objects of this class. @return The list */
     127            /// Returns the list of all existing objects of this class.
    108128            inline ObjectListBase* getObjects() const { return this->objects_; }
    109129
    110             /** @brief Sets the Factory. @param factory The factory to assign */
     130            /// Sets the Factory.
    111131            inline void addFactory(Factory* factory) { this->factory_ = factory; }
    112             /** @brief Returns true if the Identifier has a Factory. */
     132            /// Returns true if the Identifier has a Factory.
    113133            inline bool hasFactory() const { return (this->factory_ != 0); }
    114134
    115135            BaseObject* fabricate(BaseObject* creator);
    116136
    117             /** @brief Returns true if the class can be loaded through XML. */
     137            /// Returns true if the class can be loaded through XML.
    118138            inline bool isLoadable() const { return this->bLoadable_; }
    119             /** @brief Set the class to be loadable through XML or not. */
     139            /// Set the class to be loadable through XML or not.
    120140            inline void setLoadable(bool bLoadable) { this->bLoadable_ = bLoadable; }
    121141
     
    133153            static void createClassHierarchy();
    134154
    135             /** @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 */
     155            /// Returns true, if a branch of the class-hierarchy is being created, causing all new objects to store their parents.
    136156            inline static bool isCreatingHierarchy() { return (hierarchyCreatingCounter_s > 0); }
    137157
    138             /** @brief Returns the parents of the class the Identifier belongs to. @return The list of all parents */
     158            /// Returns the parents of the class the Identifier belongs to.
    139159            inline const std::set<const Identifier*>& getParents() const { return this->parents_; }
    140             /** @brief Returns the begin-iterator of the parents-list. @return The begin-iterator */
     160            /// Returns the begin-iterator of the parents-list.
    141161            inline std::set<const Identifier*>::const_iterator getParentsBegin() const { return this->parents_.begin(); }
    142             /** @brief Returns the end-iterator of the parents-list. @return The end-iterator */
     162            /// Returns the end-iterator of the parents-list.
    143163            inline std::set<const Identifier*>::const_iterator getParentsEnd() const { return this->parents_.end(); }
    144164
    145             /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
     165            /// Returns the children of the class the Identifier belongs to.
    146166            inline const std::set<const Identifier*>& getChildren() const { return this->children_; }
    147             /** @brief Returns the begin-iterator of the children-list. @return The begin-iterator */
     167            /// Returns the begin-iterator of the children-list.
    148168            inline std::set<const Identifier*>::const_iterator getChildrenBegin() const { return this->children_.begin(); }
    149             /** @brief Returns the end-iterator of the children-list. @return The end-iterator */
     169            /// Returns the end-iterator of the children-list.
    150170            inline std::set<const Identifier*>::const_iterator getChildrenEnd() const { return this->children_.end(); }
    151171
    152             /** @brief Returns the direct parents of the class the Identifier belongs to. @return The list of all direct parents */
     172            /// Returns the direct parents of the class the Identifier belongs to.
    153173            inline const std::set<const Identifier*>& getDirectParents() const { return this->directParents_; }
    154             /** @brief Returns the begin-iterator of the direct-parents-list. @return The begin-iterator */
     174            /// Returns the begin-iterator of the direct-parents-list.
    155175            inline std::set<const Identifier*>::const_iterator getDirectParentsBegin() const { return this->directParents_.begin(); }
    156             /** @brief Returns the end-iterator of the direct-parents-list. @return The end-iterator */
     176            /// Returns the end-iterator of the direct-parents-list.
    157177            inline std::set<const Identifier*>::const_iterator getDirectParentsEnd() const { return this->directParents_.end(); }
    158178
    159             /** @brief Returns the direct children the class the Identifier belongs to. @return The list of all direct children */
     179            /// Returns the direct children the class the Identifier belongs to.
    160180            inline const std::set<const Identifier*>& getDirectChildren() const { return this->directChildren_; }
    161             /** @brief Returns the begin-iterator of the direct-children-list. @return The begin-iterator */
     181            /// Returns the begin-iterator of the direct-children-list.
    162182            inline std::set<const Identifier*>::const_iterator getDirectChildrenBegin() const { return this->directChildren_.begin(); }
    163             /** @brief Returns the end-iterator of the direct-children-list. @return The end-iterator */
     183            /// Returns the end-iterator of the direct-children-list.
    164184            inline std::set<const Identifier*>::const_iterator getDirectChildrenEnd() const { return this->directChildren_.end(); }
    165185
     
    176196            static void clearNetworkIDs();
    177197
    178             /** @brief Returns the map that stores all Identifiers with their names. @return The map */
     198            /// Returns the map that stores all Identifiers with their names.
    179199            static inline const std::map<std::string, Identifier*>& getStringIdentifierMap() { return Identifier::getStringIdentifierMapIntern(); }
    180             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names. @return The const_iterator */
     200            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names.
    181201            static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapBegin() { return Identifier::getStringIdentifierMap().begin(); }
    182             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names. @return The const_iterator */
     202            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names.
    183203            static inline std::map<std::string, Identifier*>::const_iterator getStringIdentifierMapEnd() { return Identifier::getStringIdentifierMap().end(); }
    184204
    185             /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
     205            /// Returns the map that stores all Identifiers with their names in lowercase.
    186206            static inline const std::map<std::string, Identifier*>& getLowercaseStringIdentifierMap() { return Identifier::getLowercaseStringIdentifierMapIntern(); }
    187             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
     207            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their names in lowercase.
    188208            static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapBegin() { return Identifier::getLowercaseStringIdentifierMap().begin(); }
    189             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase. @return The const_iterator */
     209            /// Returns a const_iterator to the end of the map that stores all Identifiers with their names in lowercase.
    190210            static inline std::map<std::string, Identifier*>::const_iterator getLowercaseStringIdentifierMapEnd() { return Identifier::getLowercaseStringIdentifierMap().end(); }
    191211
    192             /** @brief Returns the map that stores all Identifiers with their IDs. @return The map */
     212            /// Returns the map that stores all Identifiers with their IDs.
    193213            static inline const std::map<uint32_t, Identifier*>& getIDIdentifierMap() { return Identifier::getIDIdentifierMapIntern(); }
    194             /** @brief Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs. @return The const_iterator */
     214            /// Returns a const_iterator to the beginning of the map that stores all Identifiers with their IDs.
    195215            static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapBegin() { return Identifier::getIDIdentifierMap().begin(); }
    196             /** @brief Returns a const_iterator to the end of the map that stores all Identifiers with their IDs. @return The const_iterator */
     216            /// Returns a const_iterator to the end of the map that stores all Identifiers with their IDs.
    197217            static inline std::map<uint32_t, Identifier*>::const_iterator getIDIdentifierMapEnd() { return Identifier::getIDIdentifierMap().end(); }
    198218
     
    203223            virtual void updateConfigValues(bool updateChildren = true) const = 0;
    204224
    205             /** @brief Returns true if this class has at least one config value. @return True if this class has at least one config value */
     225            /// Returns true if this class has at least one config value.
    206226            inline bool hasConfigValues() const { return this->bHasConfigValues_; }
    207227
     
    213233            ///// XMLPort /////
    214234            ///////////////////
    215             /** @brief Returns the map that stores all XMLPort params. @return The const_iterator */
     235            /// Returns the map that stores all XMLPort params.
    216236            inline const std::map<std::string, XMLPortParamContainer*>& getXMLPortParamMap() const { return this->xmlportParamContainers_; }
    217             /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort params. @return The const_iterator */
     237            /// Returns a const_iterator to the beginning of the map that stores all XMLPort params.
    218238            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapBegin() const { return this->xmlportParamContainers_.begin(); }
    219             /** @brief Returns a const_iterator to the end of the map that stores all XMLPort params. @return The const_iterator */
     239            /// Returns a const_iterator to the end of the map that stores all XMLPort params.
    220240            inline std::map<std::string, XMLPortParamContainer*>::const_iterator getXMLPortParamMapEnd() const { return this->xmlportParamContainers_.end(); }
    221241
    222             /** @brief Returns the map that stores all XMLPort objects. @return The const_iterator */
     242            /// Returns the map that stores all XMLPort objects.
    223243            inline const std::map<std::string, XMLPortObjectContainer*>& getXMLPortObjectMap() const { return this->xmlportObjectContainers_; }
    224             /** @brief Returns a const_iterator to the beginning of the map that stores all XMLPort objects. @return The const_iterator */
     244            /// Returns a const_iterator to the beginning of the map that stores all XMLPort objects.
    225245            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapBegin() const { return this->xmlportObjectContainers_.begin(); }
    226             /** @brief Returns a const_iterator to the end of the map that stores all XMLPort objects. @return The const_iterator */
     246            /// Returns a const_iterator to the end of the map that stores all XMLPort objects.
    227247            inline std::map<std::string, XMLPortObjectContainer*>::const_iterator getXMLPortObjectMapEnd() const { return this->xmlportObjectContainers_.end(); }
    228248
     
    244264            void initializeClassHierarchy(std::set<const Identifier*>* parents, bool bRootClass);
    245265
    246             /** @brief Returns the map that stores all Identifiers with their names. @return The map */
     266            /// Returns the map that stores all Identifiers with their names.
    247267            static std::map<std::string, Identifier*>& getStringIdentifierMapIntern();
    248             /** @brief Returns the map that stores all Identifiers with their names in lowercase. @return The map */
     268            /// Returns the map that stores all Identifiers with their names in lowercase.
    249269            static std::map<std::string, Identifier*>& getLowercaseStringIdentifierMapIntern();
    250             /** @brief Returns the map that stores all Identifiers with their network IDs. @return The map */
     270            /// Returns the map that stores all Identifiers with their network IDs.
    251271            static std::map<uint32_t, Identifier*>& getIDIdentifierMapIntern();
    252272
    253             /** @brief Returns the children of the class the Identifier belongs to. @return The list of all children */
     273            /// Returns the children of the class the Identifier belongs to.
    254274            inline std::set<const Identifier*>& getChildrenIntern() const { return this->children_; }
    255             /** @brief Returns the direct children of the class the Identifier belongs to. @return The list of all direct children */
     275            /// Returns the direct children of the class the Identifier belongs to.
    256276            inline std::set<const Identifier*>& getDirectChildrenIntern() const { return this->directChildren_; }
    257277
     
    259279
    260280        private:
    261             /** @brief Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents. */
     281            /// Increases the hierarchyCreatingCounter_s variable, causing all new objects to store their parents.
    262282            inline static void startCreatingHierarchy() { hierarchyCreatingCounter_s++; }
    263             /** @brief Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents. */
     283            /// Decreases the hierarchyCreatingCounter_s variable, causing the objects to stop storing their parents.
    264284            inline static void stopCreatingHierarchy()  { hierarchyCreatingCounter_s--; }
    265285
     
    297317    // ###     ClassIdentifier     ###
    298318    // ###############################
    299     //! The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
    300     /**
    301         ClassIdentifier is a Singleton, which means that only one object of a given type T exists.
     319    /**
     320        @brief The ClassIdentifier is derived from Identifier and holds all class-specific functions and variables the Identifier cannot have.
     321
     322        ClassIdentifier is a Singleton, which means that only one ClassIdentifier for a given type T exists.
    302323        This makes it possible to store information about a class, sharing them with all
    303324        objects of that class without defining static variables in every class.
    304325
    305326        To be really sure that not more than exactly one object exists (even with libraries),
    306         ClassIdentifiers are stored in the Identifier Singleton.
     327        ClassIdentifiers are stored in a static map in Identifier.
    307328    */
    308329    template <class T>
  • code/branches/doc/src/libraries/core/Iterator.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Object ObjectList
    32     @brief Definition and implementation of the Iterator class.
    33 
    34     The Iterator of a given class allows to iterate through an ObjectList. Objects in
    35     this list are cast to the template argument of the Iterator.
     32    @brief Definition of the Iterator class.
     33
     34    @anchor IteratorExample
     35
     36    @ref orxonox::Iterator "Iterator" allows to iterate through an @ref orxonox::ObjectListBase
     37    "ObjectListBase". Objects in this list are cast to the template argument @a T of Iterator<T> using
     38    @c dynamic_cast. In contrast to @ref orxonox::ObjectListIterator "ObjectListIterator<T>",
     39    @ref orxonox::Iterator "Iterator<T>" can iterate through every object-list. In practice though it
     40    is limited to objects of type @a T and its subclasses. Because of the @c dynamic_cast, this iterator
     41    is much slower than ObjectListIterator.
    3642
    3743    Usage:
     44    @code
    3845    for (Iterator<myClass> it = anyidentifier->getObjects()->begin(); it != anyidentifier->getObjects()->end(); ++it)
    3946    {
     
    4148        myClass* myObject = *it;
    4249    }
     50    @endcode
    4351*/
    4452
     
    5361namespace orxonox
    5462{
    55     //! The Iterator allows to iterate through a given ObjectList
     63    /**
     64        @brief The Iterator allows to iterate through a given ObjectList.
     65
     66        Independent of the object-list's type, the objects in the list are always casted
     67        to @a T using @c dynamic_cast.
     68
     69        @see See @ref IteratorExample "Iterator.h" for more information an example.
     70    */
    5671    template <class T = OrxonoxClass>
    5772    class Iterator
  • code/branches/doc/src/libraries/core/Language.h

    r7363 r7372  
    3535    @file
    3636    @ingroup Language
    37     @brief Definition of the Language and the LanguageEntry class.
     37    @brief Declaration of the Language and the LanguageEntry class, as well as some helper functions.
     38
     39    @anchor LanguageExample
    3840
    3941    The Language class is used, to get a localisation of a string in the configured language.
     
    4345    Usage:
    4446     - Set the entry with the default string:
     47       @code
    4548       Language::getInstance()->addEntry("label of the entry", "the string to translate");
     49       @endcode
    4650
    4751     - Get the localisation of the entry in the configured language:
     52       @code
    4853       std::cout << Language::getInstance()->getLocalisation("name of the entry") << std::endl;
     54       @endcode
     55
     56    Example:
     57    @code
     58    int age = 20;
     59    AddLanguageEntry("user_age", "Age");
     60    std::cout << GetLocalisation("user_age") << ": " << age << std::endl;
     61    @endcode
     62
     63    Resulting output:
     64    @code
     65    Age: 20
     66    @endcode
     67
     68    The language entry is now defined in @a translation_default.lang:
     69    @code
     70    user_age=Age
     71    @endcode
     72
     73    We can add a translation for another language, for example @a translation_german.lang:
     74    @code
     75    user_age=Alter
     76    @endcode
     77
     78    Now change the language in @a orxonox.ini to "german":
     79    @code
     80    language_ = "german"
     81    @endcode
     82
     83    Now you will see the translated language entry in the resulting output of the above code:
     84    @code
     85    Alter: 20
     86    @endcode
    4987*/
    5088
     
    64102    // ###      LanguageEntry      ###
    65103    // ###############################
    66     //! The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
     104    /**
     105        @brief The LanguageEntry class stores the default- and the translated string of a given entry in the language file.
     106
     107        This class belongs to the Language class.
     108    */
    67109    class _CoreExport LanguageEntry
    68110    {
     
    111153    // ###         Language        ###
    112154    // ###############################
    113     //! The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
     155    /**
     156        @brief The Language class manges the language files and entries and stores the LanguageEntry objects in a map.
     157
     158        @see See @ref LanguageExample "Language.h" for some examples.
     159    */
    114160    class _CoreExport Language : public Singleton<Language>
    115161    {
     
    140186    };
    141187
    142     //! Shortcut function for Language::addEntry
     188    /// Shortcut function for Language::addEntry
    143189    inline void AddLanguageEntry(const LanguageEntryLabel& label, const std::string& fallbackString)
    144190    {
     
    146192    }
    147193
    148     //! Shortcut function for Language::getLocalisation
     194    /// Shortcut function for Language::getLocalisation
    149195    inline const std::string& GetLocalisation(const LanguageEntryLabel& label)
    150196    {
     
    152198    }
    153199
    154     //! Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
     200    /// Shortcut function for Language::getLocalisation without printing an error in case the label doesn't exist
    155201    inline const std::string& GetLocalisation_noerror(const LanguageEntryLabel& label)
    156202    {
  • code/branches/doc/src/libraries/core/MetaObjectList.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Object ObjectList
    32     @brief Definition of the MetaObjectList class.
     32    @brief Declaration of the MetaObjectList class.
    3333
    3434    The MetaObjectList is a single-linked list, containing all list-elements and their
     
    4747    // ###  MetaObjectListElement  ###
    4848    // ###############################
    49     //! The list-element of the MetaObjectList
     49    /// The list-element of the MetaObjectList
    5050    class _CoreExport MetaObjectListElement
    5151    {
     
    6666    // ###     MetaObjectList      ###
    6767    // ###############################
    68     //!  The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
    6968    /**
     69        @brief The MetaObjectList contains ObjectListBaseElements and their ObjectListBases.
     70
    7071        The MetaObjectList is a single-linked list, containing all list-elements and their
    7172        lists wherein the object that owns the MetaObjectList is registered.
  • code/branches/doc/src/libraries/core/ObjectList.h

    r7363 r7372  
    3535    @file
    3636    @ingroup Object ObjectList
    37     @brief Definition and implementation of the ObjectList class.
     37    @brief Definition of the ObjectList class.
    3838
    39     The ObjectList is a wrapper of an ObjectListBase of a given class.
    40     Use Iterator<class> to iterate through all objects of the class.
     39    @ref orxonox::ObjectList "ObjectList<T>" is a wrapper of an @ref orxonox::ObjectListBase
     40    "ObjectListBase" of class @a T. Use @ref orxonox::ObjectListIterator "ObjectListIterator<T>"
     41    to iterate through the list.
    4142*/
    4243
     
    5556    // ###       ObjectList        ###
    5657    // ###############################
    57     //! The ObjectList contains all objects of the given class.
    5858    /**
    59         Wraps the ObjectListBase of the corresponding Identifier.
    60         Use ObjectListIterator<class> to iterate through all objects in the list.
     59        @brief The ObjectList contains all objects of the given class.
     60
     61        Wraps the ObjectListBase which contains all objects of type @a T. Use @ref ObjectListIterator
     62        "ObjectListIterator<T>" or its typedef ObjectList<T>::iterator to iterate through all objects
     63        in the list.
    6164    */
    6265    template <class T>
     
    6669            typedef ObjectListIterator<T> iterator;
    6770
    68             /** @brief Returns an Iterator to the first element in the list. @return The Iterator */
     71            /// Returns an Iterator to the first element in the list.
    6972            inline static ObjectListElement<T>* begin()
    7073            {
     
    7376            }
    7477
    75             /** @brief Returns an Iterator to the element after the last element in the list. @return The Iterator */
     78            /// Returns an Iterator to the element after the last element in the list.
    7679            inline static ObjectListElement<T>* end()
    7780            {
     
    8083            }
    8184
    82             /** @brief Returns an Iterator to the last element in the list. @return The Iterator */
     85            /// Returns an Iterator to the last element in the list.
    8386            inline static ObjectListElement<T>* rbegin()
    8487            {
     
    8790            }
    8891
    89             /** @brief Returns an Iterator to the element before the first element in the list. @return The Iterator */
     92            /// Returns an Iterator to the element before the first element in the list.
    9093            inline static ObjectListElement<T>* rend()
    9194            {
  • code/branches/doc/src/libraries/core/ObjectListBase.cc

    r7297 r7372  
    3030    @file
    3131    @brief Implementation of the ObjectListBase class.
    32 
    33     The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
    34     Newly created objects are added through the RegisterObject-macro in its constructor.
    3532*/
    3633
  • code/branches/doc/src/libraries/core/ObjectListBase.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Object ObjectList
    32     @brief Definition of the ObjectListBase class.
     32    @brief Declaration of the ObjectListBase class.
    3333
    34     The ObjectListBase is a double-linked list, used by Identifiers to store all objects of a given class.
    35     Newly created objects are added through the RegisterObject-macro in its constructor.
     34    orxonox::ObjectListBase is a double-linked list, used by @ref orxonox::Identifier "Identifiers"
     35    to store all objects of a given class. Newly created objects are added to the list through the
     36    @c RegisterObject() macro in the constructor.
    3637*/
    3738
     
    4950    // ###  ObjectListBaseElement  ###
    5051    // ###############################
    51     //! The list-element of the ObjectListBase
     52    /// The list-element of the ObjectListBase
    5253    class _CoreExport ObjectListBaseElement
    5354    {
     
    6869    // ###    ObjectListElement    ###
    6970    // ###############################
    70     //! The list-element that actually contains the object
     71    /// The list-element that actually contains the object
    7172    template <class T>
    7273    class ObjectListElement : public ObjectListBaseElement
     
    8182    // ###     ObjectListBase      ###
    8283    // ###############################
    83     //! The ObjectListBase contains all objects of a given class.
    8484    /**
    85         The ObjectListBase is used by Identifiers to store all objects of their given class.
    86         Use ObjectList<T> to get the list of all T's and Iterator<T> to iterate through them.
     85        @brief The ObjectListBase contains all objects of a given class.
     86
     87        The ObjectListBase is used by Identifiers to store all objects of their class.
     88        You can use Identifier::getObjects() to get the object-list from an Identifier.
     89        Use @ref Iterator "Iterator<T>" to iterate through them.
     90
     91        Alternatively you can also use the static helper class @ref orxonox::ObjectList "ObjectList<T>"
     92        to get the list of all objects of type @a T. Use @ref ObjectListIterator "ObjectListIterator<T>"
     93        or @ref Iterator "Iterator<T>" to iterate through them.
    8794    */
    8895    class _CoreExport ObjectListBase
     
    96103            ObjectListBaseElement* add(ObjectListBaseElement* element);
    97104
     105            /// Helper struct, used to export an element and the list to an instance of Iterator.
    98106            struct Export
    99107            {
     
    103111            };
    104112
    105             /** @brief Returns a pointer to the first element in the list. @return The element */
     113            /// Returns a pointer to the first element in the list. Works only with Iterator.
    106114            inline Export begin() { return ObjectListBase::Export(this, this->first_); }
    107             /** @brief Returns a pointer to the element after the last element in the list. @return The element */
     115            /// Returns a pointer to the element after the last element in the list. Works only with Iterator.
    108116            inline Export end() { return ObjectListBase::Export(this, 0); }
    109             /** @brief Returns a pointer to the last element in the list. @return The element */
     117            /// Returns a pointer to the last element in the list. Works only with Iterator.
    110118            inline Export rbegin() { return ObjectListBase::Export(this, this->last_); }
    111             /** @brief Returns a pointer to the element in front of the first element in the list. @return The element */
     119            /// Returns a pointer to the element in front of the first element in the list. Works only with Iterator.
    112120            inline Export rend() { return ObjectListBase::Export(this, 0); }
    113121
  • code/branches/doc/src/libraries/core/ObjectListIterator.h

    r7363 r7372  
    3030    @file
    3131    @ingroup Object ObjectList
    32     @brief Definition and implementation of the Iterator class.
    33 
    34     The ObjectListIterator of a given class allows to iterate through the
    35     ObjectList of this class, containing all objects of that type.
    36     This is the only way to access the objects stored in an ObjectList.
     32    @brief Definition of the ObjectListIterator class.
     33
     34    @anchor ObjectListIteratorExample
     35
     36    @ref orxonox::ObjectListIterator "ObjectListIterator<T>" allows to iterate through
     37    @ref orxonox::ObjectList "ObjectList<T>", containing all objects of type @a T. In contrast to
     38    @ref orxonox::Iterator "Iterator<T>", this iterator is limited to the object-list of type @a T.
     39    It is, however, much faster as it doesn't need a @c dynamic_cast.
    3740
    3841    Usage:
     42    @code
    3943    for (ObjectListIterator<myClass> it = ObjectList<myClass>::begin(); it != ObjectList<myClass>::end(); ++it)
    4044    {
     
    4246        myClass* myObject = *it;
    4347    }
     48    @endcode
     49
     50    @note @ref orxonox::ObjectList::iterator "ObjectList<T>::iterator" is identical to
     51          @ref orxonox::ObjectListIterator "ObjectListIterator<T>" (it's just a typedef).
    4452*/
    4553
     
    5361namespace orxonox
    5462{
    55     //! The Iterator allows to iterate through the ObjectList of a given class.
     63    /**
     64        @brief ObjectListIterator<T> allows to iterate through the ObjectList of class @a T.
     65
     66        @see See @ref ObjectListIteratorExample "ObjectListIterator.h" for more information an example.
     67    */
    5668    template <class T>
    5769    class ObjectListIterator
     
    218230
    219231        private:
    220             ObjectListElement<T>* element_;        //!< The element the Iterator points at
     232            ObjectListElement<T>* element_;        //!< The element the iterator points at
    221233    };
    222234}
  • code/branches/doc/src/libraries/core/OrxonoxClass.h

    r7363 r7372  
    5959namespace orxonox
    6060{
    61     //! The class all objects and interfaces of the game-logic (not the engine) are derived from.
    6261    /**
    63         The BaseObject and Interfaces are derived with 'virtual public OrxonoxClass' from OrxonoxClass.
     62        @brief The class all objects and interfaces of the game-logic (not the engine) are derived from.
     63
     64        The BaseObject and Interfaces are derived with @c virtual @c public @c OrxonoxClass from OrxonoxClass.
    6465        OrxonoxClass is needed to create the class-hierarchy at startup and to store the Identifier and the MetaObjectList.
    6566    */
     
    8283            void unregisterObject();
    8384
    84             /** @brief Function to collect the SetConfigValue-macro calls. */
     85            /// Function to collect the SetConfigValue-macro calls.
    8586            void setConfigValues() {};
    8687
    87             /** @brief Returns the Identifier of the object. @return The Identifier */
     88            /// Returns the Identifier of the object.
    8889            inline Identifier* getIdentifier() const { return this->identifier_; }
    8990
     
    137138            }
    138139
    139             //! Version of getDerivedPointer with template
     140            /// Version of getDerivedPointer with template
    140141            template <class T> FORCEINLINE T* getDerivedPointer(unsigned int classID)
    141142            {   return static_cast<T*>(this->getDerivedPointer(classID));   }
    142             //! Const version of getDerivedPointer with template
     143            /// Const version of getDerivedPointer with template
    143144            template <class T> FORCEINLINE const T* getDerivedPointer(unsigned int classID) const
    144145            {   return const_cast<OrxonoxClass*>(this)->getDerivedPointer<T>(classID);   }
     
    148149
    149150        private:
    150             /** @brief Increments the reference counter (for smart pointers). */
     151            /// Increments the reference counter (for smart pointers).
    151152            inline void incrementReferenceCount()
    152153                { ++this->referenceCount_; }
    153             /** @brief Decrements the reference counter (for smart pointers). */
     154            /// Decrements the reference counter (for smart pointers).
    154155            inline void decrementReferenceCount()
    155156            {
     
    159160            }
    160161
    161             /** @brief Register a weak pointer which points to this object. */
     162            /// Register a weak pointer which points to this object.
    162163            template <class T>
    163164            inline void registerWeakPtr(WeakPtr<T>* pointer)
    164165                { this->weakPointers_.insert(reinterpret_cast<WeakPtr<OrxonoxClass>*>(pointer)); }
    165             /** @brief Unegister a weak pointer which pointed to this object before. */
     166            /// Unegister a weak pointer which pointed to this object before.
    166167            template <class T>
    167168            inline void unregisterWeakPtr(WeakPtr<T>* pointer)
     
    175176            std::set<WeakPtr<OrxonoxClass>*> weakPointers_; //!< All weak pointers which point to this object (and like to get notified if it dies)
    176177
    177             //! 'Fast map' that holds this-pointers of all derived types
     178            /// 'Fast map' that holds this-pointers of all derived types
    178179            std::vector<std::pair<unsigned int, void*> > objectPointers_;
    179180    };
  • code/branches/doc/src/libraries/core/SubclassIdentifier.h

    r7363 r7372  
    3232    @brief Definition of SubclassIdentifier.
    3333
     34    @anchor SubclassIdentifierExample
     35
    3436    SubclassIdentifier is a separated class, acting like an Identifier, but has a given class.
    3537    You can only assign Identifiers of exactly the given class or of a derivative to a SubclassIdentifier.
     38
     39    Example:
     40
     41    You can assign an Identifier either through the constructor or by using the assignment @c operator=:
     42    @code
     43    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
     44    @endcode
     45
     46    The @c operator-> is overloaded an returns the assigned Identifier. That way you can just call
     47    functions of the assigned Identifier by using @c ->function():
     48    @code
     49    SubclassIdentifier<BaseClass> identifier = Class(SubClass);
     50    identifier->getName();      // returns "SubClass"
     51    @endcode
     52
     53    There are two possibilities to create an object out of a SubclassIdentifier: Either you just use
     54    the @c fabricate() function of the assigned Identifier through the overloaded @c operator->, which
     55    returns a @c BaseObject* pointer, or you use the function of SubclassIdentifier, this time by using
     56    @c operator., which returns a @c BaseClass* pointer (@a BaseClass is the baseclass specified by the
     57    template argument):
     58    @code
     59    identifier->fabricate();    // calls Identifier::fabricate(), creates a SubClass, returns a BaseObject* pointer
     60
     61    identifier.fabricate();     // calls SubclassIdentifier::fabricate(), creates a SubClass, returns a BaseClass* pointer
     62    @endcode
    3663*/
    3764
     
    5077    // ###   SubclassIdentifier    ###
    5178    // ###############################
    52     //! The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
    5379    /**
     80        @brief The SubclassIdentifier acts almost like an Identifier, but has some prerequisites.
     81
    5482        You can only assign an Identifier that belongs to a class T (or derived) to a SubclassIdentifier<T>.
    55         If you assign something else, the program aborts.
    56         Because we know the minimum type, a dynamic_cast is done, which makes it easier to create a new object.
     83        If you assign something else, the program prints an error.
     84
     85        Because we know the base-type, a @c dynamic_cast is done, which makes it easier to create a new object.
     86
     87        @see See @ref SubclassIdentifierExample "SubclassIdentifier.h" for some examples.
    5788    */
    5889    template <class T>
     
    6091    {
    6192        public:
    62             /**
    63                 @brief Constructor: Automaticaly assigns the Identifier of the given class.
    64             */
     93            /// Constructor: Automaticaly assigns the Identifier of the given class.
    6594            SubclassIdentifier()
    6695            {
     
    6897            }
    6998
    70             /**
    71                 @brief Constructor: Assigns the given Identifier.
    72                 @param identifier The Identifier
    73             */
     99            /// Constructor: Assigns the given Identifier.
    74100            SubclassIdentifier(Identifier* identifier)
    75101            {
     
    77103            }
    78104
    79             /**
    80                 @brief Copyconstructor: Assigns the identifier of the other SubclassIdentifier.
    81                 @param identifier The other SublcassIdentifier
    82             */
     105            /// Copyconstructor: Assigns the identifier of another SubclassIdentifier.
    83106            template <class O>
    84107            SubclassIdentifier(const SubclassIdentifier<O>& identifier)
     
    114137            }
    115138
    116             /**
    117                 @brief Overloading of the = operator: assigns the identifier of the other SubclassIdentifier.
    118                 @param identifier The other SublcassIdentifier
    119             */
     139            /// Overloading of the = operator: assigns the identifier of another SubclassIdentifier.
    120140            template <class O>
    121141            SubclassIdentifier<T>& operator=(const SubclassIdentifier<O>& identifier)
     
    124144            }
    125145
    126             /**
    127                 @brief Overloading of the * operator: returns the assigned identifier.
    128             */
     146            /// Overloading of the * operator: returns the assigned identifier.
    129147            inline Identifier* operator*() const
    130148            {
     
    132150            }
    133151
    134             /**
    135                 @brief Overloading of the -> operator: returns the assigned identifier.
    136             */
     152            /// Overloading of the -> operator: returns the assigned identifier.
    137153            inline Identifier* operator->() const
    138154            {
     
    140156            }
    141157
    142             /**
    143                 @brief Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
    144             */
     158            /// Returns the assigned identifier. This allows you to assign a SubclassIdentifier to a normal Identifier*.
    145159            inline operator Identifier*() const
    146160            {
     
    148162            }
    149163
    150             /**
    151                 @brief Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
    152                 @return The new object
    153             */
     164            /// Creates a new object of the type of the assigned Identifier and dynamic_casts it to the minimal type given by T.
    154165            T* fabricate(BaseObject* creator) const
    155166            {
     
    182193            }
    183194
    184             /** @brief Returns the assigned identifier. @return The identifier */
     195            /// Returns the assigned identifier.
    185196            inline Identifier* getIdentifier() const
    186197                { return this->identifier_; }
  • code/branches/doc/src/libraries/core/Super.h

    r7363 r7372  
    3737    @brief Definition of all super-function related macros.
    3838
    39     This file defines all macros needed to add a new "super-function".
    40     If you add a super-function, you can call SUPER(myclass, functionname) inside your
    41     code and the function of the parentclass gets called. This is comparable with
    42     super.functionname() in Java or other languages.
    43 
    44     This works only with virtual functions that return nothing (void) and belong to
    45     classes that have an Identifier. Arguments however are supported.
    46 
    47     To add a new super-function, you have process 4 steps:
    48 
    49     1) Add a new SUPER macro
    50        This allows you to call the super-function in your code.
    51        Location: This file (Super.h), marked with --> HERE <-- comments (1/3)
    52 
    53     2) Call the SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros.
    54        This defines some global classes and templates, needed to create and call the super-functions.
    55        Location: This file (Super.h), marked with --> HERE <-- comments (2/3)
    56 
    57     3) Call the SUPER_INTRUSIVE_DECLARATION macro.
    58        This will be included into the declaration of ClassIdentifier<T>.
    59        Location: This file (Super.h), marked with --> HERE <-- comments (3/3)
    60 
    61     4) Call the SUPER_FUNCTION macro.
     39    This file defines all macros needed to add a new "super-function". If you add
     40    a super-function, you can call <tt>SUPER(myclass, functionname, arguments)</tt>
     41    inside your code and the function of the parent-class gets called. This is comparable
     42    to <tt>super.functionname(arguments)</tt> in Java or other languages.
     43
     44    This works only with virtual functions that return nothing (@c void) and belong to
     45    classes that have an @ref orxonox::Identifier "Identifier". Arguments however are
     46    supported, there's no limitation for their number and type, except that the type has
     47    to be known in Super.h.
     48
     49    To add a new super-function, you have to process 4 steps:
     50
     51    -# Add a new @c SUPER macro <br />
     52       This allows you to call the super-function in your code. <br />
     53       Location: This file (Super.h), marked with "--> HERE <--" comments (1/3)
     54    -# Call the @c SUPER_FUNCTION_GLOBAL_DECLARATION_PART1/2 macros. <br />
     55       This defines some global classes and templates, needed to create and call the super-functions. <br />
     56       Location: This file (Super.h), marked with "--> HERE <--" comments (2/3)
     57    -# Call the @c SUPER_INTRUSIVE_DECLARATION macro. <br />
     58       This will be included into the declaration of @c ClassIdentifier<T>. <br />
     59       Location: This file (Super.h), marked with "--> HERE <--" comments (3/3)
     60    -# Call the @c SUPER_FUNCTION macro. <br />
    6261       This defines a partially specialized template that will decide if a class is "super" to another class.
    63        If the check returns true, a SuperFunctionCaller gets created, which will be used by the SUPER macro.
     62       If the check returns true, a @c SuperFunctionCaller gets created, which will be used by the @c SUPER macro.
    6463       You have to add this into the header-file of the baseclass of the super-function (the class that first
    6564       implements the function), below the class declaration. You can't call it directly in this file, because
    66        otherwise you had to include the headerfile right here, which would cause some ugly backdependencies,
    67        include loops and slower compilation.
    68        Dont forget to include Super.h in the header-file.
     65       otherwise you had to include the headerfile right here, which would cause some ugly back-dependencies,
     66       include loops and slower compilation. <br />
     67       Dont forget to include Super.h in the header-file. <br />
    6968       Location: The header-file of the baseclass (Baseclass.h), below the class declaration
    7069*/
     
    211210    */
    212211
    213     // SUPER-macro: Calls Parent::functionname() where Parent is the direct parent of classname
     212    /// SUPER-macro: Calls Parent::functionname(...) where Parent is the direct parent of @a classname
    214213    #ifdef ORXONOX_COMPILER_MSVC
    215214        #define SUPER(classname, functionname, ...) \
Note: See TracChangeset for help on using the changeset viewer.