Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 7, 2010, 12:58:52 AM (14 years ago)
Author:
landauf
Message:

enhanced documentation of some core classes and added examples

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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}
Note: See TracChangeset for help on using the changeset viewer.