Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 7, 2010, 11:24:47 PM (14 years ago)
Author:
landauf
Message:

added documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • code/branches/doc/src/libraries/core/ConfigFileManager.h

    r7363 r7373  
    3030    @file
    3131    @ingroup Config ConfigFile
     32    @brief Declaration of ConfigFileManager and its helper classes.
    3233*/
    3334
    … …  
    5152    // ConfigFileEntry //
    5253    /////////////////////
     54    /**
     55        @brief This class represents an entry in the config file.
     56
     57        This class is pure virtual. Use one of the derived classes to define the type of the entry.
     58    */
    5359    class _CoreExport ConfigFileEntry
    5460    {
    5561        public:
     62            /// Destructor
    5663            virtual ~ConfigFileEntry() {};
     64
     65            /// Changes the value of the entry.
    5766            virtual void setValue(const std::string& value) = 0;
     67            /// Returns the value of the entry.
    5868            virtual const std::string& getValue() const = 0;
     69
     70            /// Returns the name of the entry
    5971            virtual const std::string& getName() const = 0;
     72
     73            /// Changes the comment of the entry (will be placed after the value)
    6074            virtual void setComment(const std::string& comment) = 0;
     75
     76            /// Returns the index of the entry in a vector (used only if it is a vector)
    6177            virtual unsigned int getIndex() const { return 0; }
     78
     79            /// Defines if this entry is treated as string which means some special treatment of special characters.
    6280            virtual void setString(bool bString) = 0;
     81
     82            /// Returns the line as it will be stored in the config file.
    6383            virtual const std::string& getFileEntry() const = 0;
    6484    };
    … …  
    6888    // ConfigFileEntryValue //
    6989    //////////////////////////
     90    /**
     91        @brief This class represents a normal value in the config file.
     92    */
    7093    class _CoreExport ConfigFileEntryValue : public ConfigFileEntry
    7194    {
    7295        public:
     96            /**
     97                @brief Constructor: Initializes the entry.
     98
     99                @param name                 The name of the entry
     100                @param value                The value of the entry
     101                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     102                @param additionalComment    An optional comment that will be placed behind the value in the config file
     103            */
    73104            inline ConfigFileEntryValue(const std::string& name, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    74105                : name_(name)
    … …  
    78109                { this->update(); }
    79110
     111            /// Destructor
    80112            inline virtual ~ConfigFileEntryValue() {}
    81113
    … …  
    97129                { return this->fileEntry_; }
    98130
     131            /// Returns the "key" of the value (in this case it's just the name of the entry, but for vectors it's different)
    99132            inline virtual const std::string& getKeyString() const
    100133                { return this->name_; }
    … …  
    103136            virtual void update();
    104137
    105             const std::string name_;
    106             std::string value_;
    107             std::string additionalComment_;
    108             std::string fileEntry_;
    109             bool bString_;
     138            const std::string name_;            ///< The name of the value
     139            std::string value_;                 ///< The value
     140            std::string additionalComment_;     ///< The additional comment
     141            std::string fileEntry_;             ///< The string as it will be stored in the config file
     142            bool bString_;                      ///< If true, the value is treated as string which means some special treatment of special characters.
    110143    };
    111144
    … …  
    114147    // ConfigFileEntryVectorValue //
    115148    ////////////////////////////////
     149    /**
     150        @brief Subclass of ConfigFileEntryValue, represents an element of a vector.
     151    */
    116152    class _CoreExport ConfigFileEntryVectorValue : public ConfigFileEntryValue
    117153    {
    118154        public:
     155            /**
     156                @brief Constructor: Initializes the entry.
     157
     158                @param name                 The name of the vector
     159                @param index                The index of the element in the vector
     160                @param value                The value of the element
     161                @param bString              If true, the value is treated as string which means some special treatment of special characters.
     162                @param additionalComment    An optional comment that will be placed behind the value in the config file
     163            */
    119164            inline ConfigFileEntryVectorValue(const std::string& name, unsigned int index, const std::string& value = "", bool bString = false, const std::string& additionalComment = "")
    120165                : ConfigFileEntryValue(name, value, bString, additionalComment)
    … …  
    122167                { this->update(); /*No virtual calls in base class ctor*/ }
    123168
     169            /// Destructor
    124170            inline ~ConfigFileEntryVectorValue() {}
    125171
    … …  
    127173                { return this->index_; }
    128174
     175            /// Returns the "key" of the value (the name of the vector plus the index of the element)
    129176            inline const std::string& getKeyString() const
    130177                { return this->keyString_; }
    … …  
    133180            void update();
    134181
    135             unsigned int index_;
    136             std::string keyString_;
     182            unsigned int index_;        ///< The index of the element in the vector
     183            std::string keyString_;     ///< The full name of the entry (the name of the vector plus the index of the element)
    137184    };
    138185
    … …  
    141188    // ConfigFileEntryComment //
    142189    ////////////////////////////
     190    /**
     191        @brief This class represents a line in the config file which contains only a comment.
     192    */
    143193    class _CoreExport ConfigFileEntryComment : public ConfigFileEntry
    144194    {
    145195        public:
     196            /// Constructor: Initializes the object.
    146197            inline ConfigFileEntryComment(const std::string& comment) : comment_(comment) {}
     198
     199            /// Destructor
    147200            inline virtual ~ConfigFileEntryComment() {}
    148201
    … …  
    164217                { return this->comment_; }
    165218
    166             inline virtual const std::string& getKeyString() const
    167                 { return BLANKSTRING; }
    168 
    169219        private:
    170             std::string comment_;
     220            std::string comment_;   ///< The comment
    171221    };
    172222
    … …  
    175225    // ConfigFileSection //
    176226    ///////////////////////
     227    /**
     228        @brief Represents a section in a config file.
     229
     230        A section has a name and a list of config values.
     231    */
    177232    class _CoreExport ConfigFileSection
    178233    {
    … …  
    181236
    182237        public:
     238            /**
     239                @brief Constructor: Initializes the section.
     240
     241                @param name The name of the section
     242                @param additionalComment An additional comment placed after the title of the section in the config file
     243            */
    183244            inline ConfigFileSection(const std::string& name, const std::string& additionalComment = "")
    184245                : name_(name)
    … …  
    188249            ~ConfigFileSection();
    189250
     251            /// Returns the name of the section.
    190252            inline const std::string& getName() const
    191253                { return this->name_; }
    192254
     255            /// Changes the comment which is placed after the title of the section in the config file.
    193256            inline void setComment(const std::string& comment)
    194257                { this->additionalComment_ = comment; }
    195258
     259            /**
     260                @brief Stores a value in the section. If the entry doesn't exist, it's created.
     261
     262                @param name     The name of the entry
     263                @param value    The new value
     264                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     265            */
    196266            inline void setValue(const std::string& name, const std::string& value, bool bString)
    197267                { this->getOrCreateEntry(name, value, bString)->setValue(value); }
     268            /**
     269                @brief Returns the value of a given entry in the section. Returns a blank string if the value doesn't exist.
     270
     271                @param name     The name of the entry
     272                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     273            */
    198274            inline const std::string& getValue(const std::string& name, bool bString)
    199275            {
    … …  
    201277                if (entry)
    202278                {
    203                     entry->setString(bString);
     279                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    204280                    return entry->getValue();
    205281                }
    206282                return BLANKSTRING;
    207283            }
     284            /**
     285                @brief Returns the value of a given entry in the section. If it doesn't exist, the entry is created using the fallback value.
     286
     287                @param name     The name of the entry
     288                @param fallback The value that will be used if the entry doesn't exist
     289                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     290            */
    208291            inline const std::string& getOrCreateValue(const std::string& name, const std::string& fallback, bool bString)
    209292                { return this->getOrCreateEntry(name, fallback, bString)->getValue(); }
    210293
     294            /**
     295                @brief Stores the value of an element of a vector in the section. If the entry doesn't exist, it's created.
     296
     297                @param name     The name of the vector
     298                @param index    The index of the element in the vector
     299                @param value    The new value
     300                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     301            */
    211302            inline void setValue(const std::string& name, unsigned int index, const std::string& value, bool bString)
    212303                { this->getOrCreateEntry(name, index, value, bString)->setValue(value); }
     304            /**
     305                @brief Returns the value of a given element of a vector in the section. Returns a blank string if the value doesn't exist.
     306
     307                @param name     The name of the vector
     308                @param index    The index of the element in the vector
     309                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     310            */
    213311            inline const std::string& getValue(const std::string& name, unsigned int index, bool bString)
    214312            {
    … …  
    216314                if (entry)
    217315                {
    218                     entry->setString(bString);
     316                    entry->setString(bString);  // if the entry was loaded from the config file, we have to tell it if it's a string
    219317                    return entry->getValue();
    220318                }
    221319                return BLANKSTRING;
    222320            }
     321            /**
     322                @brief Returns the value of a given element of a vector in the section. If it doesn't exist, the entry is created using the fallback value.
     323
     324                @param name     The name of the vector
     325                @param index    The index of the element in the vector
     326                @param fallback The value that will be used if the entry doesn't exist
     327                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     328            */
    223329            inline const std::string& getOrCreateValue(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    224330                { return this->getOrCreateEntry(name, index, fallback, bString)->getValue(); }
    … …  
    230336
    231337        private:
     338            /// Returns the list of entries in this section.
    232339            std::list<ConfigFileEntry*>& getEntries()
    233340                { return this->entries_; }
     341            /// Returns the begin-iterator of the list of entries in this section.
    234342            std::list<ConfigFileEntry*>::const_iterator getEntriesBegin() const
    235343                { return this->entries_.begin(); }
     344            /// Returns the end-iterator of the list of entries in this section.
    236345            std::list<ConfigFileEntry*>::const_iterator getEntriesEnd() const
    237346                { return this->entries_.end(); }
    … …  
    241350
    242351            ConfigFileEntry* getEntry(const std::string& name) const;
     352            /**
     353                @brief Returns the entry with given name. If it doesn't exist, the entry is created using the fallback value.
     354
     355                @param name     The name of the entry
     356                @param fallback The value that will be used if the entry doesn't exist
     357                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     358            */
    243359            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, const std::string& fallback, bool bString)
    244360                { return (*this->getOrCreateEntryIterator(name, fallback, bString)); }
     361
    245362            ConfigFileEntry* getEntry(const std::string& name, unsigned int index) const;
     363            /**
     364                @brief Returns the entry that contains an element of a vector with given name. If it doesn't exist, the entry is created using the fallback value.
     365
     366                @param name     The name of the entry
     367                @param index    The index of the element in the vector
     368                @param fallback The value that will be used if the entry doesn't exist
     369                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     370            */
    246371            inline ConfigFileEntry* getOrCreateEntry(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    247372                { return (*this->getOrCreateEntryIterator(name, index, fallback, bString)); }
    248373
    249             std::string name_;
    250             std::string additionalComment_;
    251             std::list<ConfigFileEntry*> entries_;
    252             bool bUpdated_;
     374            std::string name_;                      ///< The name of the section
     375            std::string additionalComment_;         ///< The additional comment which is placed after the title of the section in the config file
     376            std::list<ConfigFileEntry*> entries_;   ///< The list of entries in this section
     377            bool bUpdated_;                         ///< True if an entry is created
    253378    };
    254379
    … …  
    257382    // ConfigFile //
    258383    ////////////////
     384    /**
     385        @brief This class represents a config file, which is stored on the hard-disk and contains config values in different sections.
     386
     387        It provides an interface to manipulate the sections and values.
     388    */
    259389    class _CoreExport ConfigFile
    260390    {
    … …  
    268398            virtual void clear();
    269399
     400            /// Returns the file-name of this config file
    270401            inline const std::string& getFilename()
    271402                { return this->filename_; }
    272403
     404            /**
     405                @brief Stores a value in the config file. If the entry or its section doesn't exist, it's created.
     406
     407                @param section  The name of the section
     408                @param name     The name of the entry
     409                @param value    The new value
     410                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     411            */
    273412            inline void setValue(const std::string& section, const std::string& name, const std::string& value, bool bString)
    274413            {
    … …  
    276415                this->save();
    277416            }
     417            /**
     418                @brief Returns the value of a given entry in the config file. Returns a blank string if the value doesn't exist.
     419
     420                @param section  The name of the section
     421                @param name     The name of the entry
     422                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     423            */
    278424            inline const std::string& getValue(const std::string& section, const std::string& name, bool bString)
    279425            {
    … …  
    281427                return (sectionPtr ? sectionPtr->getValue(name, bString) : BLANKSTRING);
    282428            }
    283             const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString);
    284 
     429            /**
     430                @brief Returns the value of a given entry in the config file. If it doesn't exist, the entry is created using the fallback value.
     431
     432                @param section  The name of the section
     433                @param name     The name of the entry
     434                @param fallback The value that will be used if the entry doesn't exist
     435                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     436            */
     437            inline const std::string& getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
     438            {
     439                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
     440                this->saveIfUpdated();
     441                return output;
     442            }
     443
     444            /**
     445                @brief Stores the value of an element of a vector in the config file. If the entry or its section doesn't exist, it's created.
     446
     447                @param section  The name of the section
     448                @param name     The name of the vector
     449                @param index    The index of the element in the vector
     450                @param value    The new value
     451                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     452            */
    285453            inline void setValue(const std::string& section, const std::string& name, unsigned int index, const std::string& value, bool bString)
    286454            {
    … …  
    288456                this->save();
    289457            }
     458            /**
     459                @brief Returns the value of a given element of a vector in the config file. Returns a blank string if the value doesn't exist.
     460
     461                @param section  The name of the section
     462                @param name     The name of the vector
     463                @param index    The index of the element in the vector
     464                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     465            */
    290466            inline const std::string& getValue(const std::string& section, const std::string& name, unsigned int index, bool bString)
    291467            {
    … …  
    293469                return (sectionPtr ? sectionPtr->getValue(name, index, bString) : BLANKSTRING);
    294470            }
    295             const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString);
     471            /**
     472                @brief Returns the value of a given element of a vector in the config file. If it doesn't exist, the entry is created using the fallback value.
     473
     474                @param section  The name of the section
     475                @param name     The name of the vector
     476                @param index    The index of the element in the vector
     477                @param fallback The value that will be used if the entry doesn't exist
     478                @param bString  If true, the value is treated as string which means some special treatment of special characters.
     479            */
     480            const std::string& getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
     481            {
     482                const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
     483                this->saveIfUpdated();
     484                return output;
     485            }
    296486
    297487            void deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex = 0);
     488            /**
     489                @brief Returns the size of a config vector.
     490                @param section  The section of the vector
     491                @param name     The name of the vector
     492            */
    298493            inline unsigned int getVectorSize(const std::string& section, const std::string& name) const
    299494            {
    … …  
    302497            }
    303498
    304             static const char* DEFAULT_CONFIG_FOLDER;
     499            static const char* DEFAULT_CONFIG_FOLDER;   ///< The folder where the default config files will be stored
    305500
    306501        protected:
    … …  
    308503            ConfigFileSection* getOrCreateSection(const std::string& section);
    309504
    310             std::list<ConfigFileSection*> sections_;
     505            std::list<ConfigFileSection*> sections_;    ///< A list of sections in this config file
    311506
    312507        private:
    313508            void saveIfUpdated();
    314             const std::string filename_;
    315             const bool bCopyFallbackFile_;
    316             bool bUpdated_;
     509
     510            const std::string filename_;                ///< The filename of this config file
     511            const bool bCopyFallbackFile_;              ///< If true, the default config file is copied into the config-directory before loading the file
     512            bool bUpdated_;                             ///< Becomes true if a section is added
    317513    };
    318514
    … …  
    321517    // SettingsConfigFile //
    322518    ////////////////////////
     519    /**
     520        @brief Child class of ConfigFile, used to store the settings of the game.
     521
     522        In addition to ConfigFile, this class provides an interface to manipulate the settings
     523        with console commands and to cache entries in instances of ConfigValueContainer.
     524
     525        SettingsConfigFile is a Singleton, meaning there's only one instance of this class
     526        (and thus only one config file that stores settings).
     527    */
    323528    class _CoreExport SettingsConfigFile // tolua_export
    324529        : public ConfigFile, public Singleton<SettingsConfigFile>
    … …  
    343548            void removeConfigValueContainer(ConfigValueContainer* container);
    344549
     550            /// Returns a set containing the names of all sections in this config file.
    345551            inline const std::set<std::string>& getSectionNames()
    346552                { return this->sectionNames_; }
     553            /// Returns the lower-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    347554            inline ContainerMap::const_iterator getContainerLowerBound(const std::string section)
    348555                { return this->containers_.lower_bound(section); }
     556            /// Returns the upper-bound-iterator of the @ref ConfigValueContainer "config value containers" for the given section.
    349557            inline ContainerMap::const_iterator getContainerUpperBound(const std::string section)
    350558                { return this->containers_.upper_bound(section); }
    … …  
    356564            bool configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&));
    357565
    358             ContainerMap containers_;
    359             std::set<std::string> sectionNames_;
    360             static SettingsConfigFile* singletonPtr_s;
     566            ContainerMap containers_;                   ///< Stores all @ref ConfigValueContainer "config value containers"
     567            std::set<std::string> sectionNames_;        ///< Stores all section names
     568            static SettingsConfigFile* singletonPtr_s;  ///< The singleton pointer
    361569    }; // tolua_export
    362570
    … …  
    365573    // ConfigFileManager //
    366574    ///////////////////////
     575    /**
     576        @brief Manages the different config files (settings, calibration, etc). Implemented as Singleton.
     577    */
    367578    class _CoreExport ConfigFileManager : public Singleton<ConfigFileManager>
    368579    {
    … …  
    374585            void setFilename(ConfigFileType::Value type, const std::string& filename);
    375586
     587            /// Returns the config file of a given type (settings, calibration, etc.)
    376588            inline ConfigFile* getConfigFile(ConfigFileType::Value type)
    377589            {
    … …  
    381593
    382594        private:
    383             ConfigFileManager(const ConfigFileManager&);
    384 
    385             boost::array<ConfigFile*, 3> configFiles_;
    386             static ConfigFileManager* singletonPtr_s;
     595            ConfigFileManager(const ConfigFileManager&);    ///< Copy-constructor: not implemented
     596
     597            boost::array<ConfigFile*, 3> configFiles_;      ///< Stores the config files for each type in an array (must have the same size like ConfigFileType::Value)
     598            static ConfigFileManager* singletonPtr_s;       ///< Stores the singleton-pointer
    387599    };
    388600} // tolua_export
Note: See TracChangeset for help on using the changeset viewer.