Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
Timestamp:
Sep 11, 2010, 12:34:00 AM (14 years ago)
Author:
landauf
Message:

merged doc branch back to trunk

Location:
code/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • code/trunk

  • code/trunk/src/libraries/core/ConfigFileManager.cc

    r7284 r7401  
    2727 */
    2828
     29/**
     30    @file
     31    @brief Implementation of ConfigFileManager and its helper classes.
     32*/
     33
    2934#include "ConfigFileManager.h"
    3035
    … …  
    4348    // ConfigFileEntryValue //
    4449    //////////////////////////
    45 
     50    /**
     51        @brief Updates the string that will be stored in the file after one of it's components (name, value, comment) has changed.
     52    */
    4653    void ConfigFileEntryValue::update()
    4754    {
    … …  
    6370    // ConfigFileEntryVectorValue //
    6471    ////////////////////////////////
     72    /**
     73        @brief Updates the string that will be stored in the file after one of it's components (name, value, index, comment) has changed.
     74    */
    6575    void ConfigFileEntryVectorValue::update()
    6676    {
    … …  
    7383    // ConfigFileSection //
    7484    ///////////////////////
     85    /**
     86        @brief Destructor: Deletes all entries.
     87    */
    7588    ConfigFileSection::~ConfigFileSection()
    7689    {
    … …  
    7992    }
    8093
     94    /**
     95        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     96
     97        @param name         The name of the vector
     98        @param startindex   The index of the first element that will be deleted
     99    */
    81100    void ConfigFileSection::deleteVectorEntries(const std::string& name, unsigned int startindex)
    82101    {
    … …  
    95114    }
    96115
     116    /**
     117        @brief Returns the size of a config vector.
     118        @param name     The name of the vector
     119    */
    97120    unsigned int ConfigFileSection::getVectorSize(const std::string& name) const
    98121    {
    … …  
    108131    }
    109132
     133    /**
     134        @brief Returns the title and comment of the section as it will be stored in the file.
     135    */
    110136    std::string ConfigFileSection::getFileEntry() const
    111137    {
    … …  
    116142    }
    117143
     144    /**
     145        @brief Returns the entry with given name (or NULL if it doesn't exist).
     146
     147        @param name     The name of the entry
     148    */
    118149    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name) const
    119150    {
    … …  
    126157    }
    127158
     159    /**
     160        @brief Returns the entry of a vector element with given name and index (or NULL if it doesn't exist).
     161
     162        @param name     The name of the vector
     163        @param index    The index of the element in the vector
     164    */
    128165    ConfigFileEntry* ConfigFileSection::getEntry(const std::string& name, unsigned int index) const
    129166    {
    … …  
    136173    }
    137174
     175    /**
     176        @brief Returns the iterator to the entry with given name. If the entry doesn't exist, it is created using the fallback value.
     177
     178        @param name     The name of the entry
     179        @param fallback The value that will be used if the entry doesn't exist
     180        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     181    */
    138182    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, const std::string& fallback, bool bString)
    139183    {
    … …  
    152196    }
    153197
     198    /**
     199        @brief Returns the iterator to the entry of a vector element with given name and index. If the entry doesn't exist, it is created using the fallback value.
     200
     201        @param name     The name of the vector
     202        @param index    The index of the element in the vector
     203        @param fallback The value that will be used if the entry doesn't exist
     204        @param bString  If true, the value is treated as string which means some special treatment of special characters.
     205    */
    154206    std::list<ConfigFileEntry*>::iterator ConfigFileSection::getOrCreateEntryIterator(const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    155207    {
    … …  
    178230    const char* ConfigFile::DEFAULT_CONFIG_FOLDER = "defaultConfig";
    179231
     232    /**
     233        @brief Constructor: Initializes the config file.
     234        @param filename The file-name of this config file
     235        @param bCopyFallbackFile If true, the default config file is copied into the config-directory before loading the file
     236    */
    180237    ConfigFile::ConfigFile(const std::string& filename, bool bCopyFallbackFile)
    181238        : filename_(filename)
    … …  
    185242    }
    186243
     244    /**
     245        @brief Destructor: Deletes all sections and entries.
     246    */
    187247    ConfigFile::~ConfigFile()
    188248    {
    … …  
    190250    }
    191251
     252    /**
     253        @brief Loads the config file from the hard-disk and reads the sections and their values.
     254    */
    192255    void ConfigFile::load()
    193256    {
    … …  
    318381    }
    319382
     383    /**
     384        @brief Writes the sections and values to the hard-disk.
     385    */
    320386    void ConfigFile::save() const
    321387    {
    … …  
    323389    }
    324390
     391    /**
     392        @brief Writes the sections and values to a given file on the hard-disk.
     393    */
    325394    void ConfigFile::saveAs(const std::string& filename) const
    326395    {
    … …  
    354423    }
    355424
     425    /**
     426        @brief Deletes all sections (which again delete all their values) and clears the list of sections.
     427    */
    356428    void ConfigFile::clear()
    357429    {
    … …  
    361433    }
    362434
    363     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, const std::string& fallback, bool bString)
    364     {
    365         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, fallback, bString);
    366         this->saveIfUpdated();
    367         return output;
    368     }
    369 
    370     const std::string& ConfigFile::getOrCreateValue(const std::string& section, const std::string& name, unsigned int index, const std::string& fallback, bool bString)
    371     {
    372         const std::string& output = this->getOrCreateSection(section)->getOrCreateValue(name, index, fallback, bString);
    373         this->saveIfUpdated();
    374         return output;
    375     }
    376 
     435    /**
     436        @brief Deletes all elements of a config vector if their index is greater or equal to @a startindex.
     437
     438        @param section      The name of the section
     439        @param name         The name of the vector
     440        @param startindex   The index of the first element that will be deleted
     441    */
    377442    void ConfigFile::deleteVectorEntries(const std::string& section, const std::string& name, unsigned int startindex)
    378443    {
    … …  
    384449    }
    385450
     451    /**
     452        @brief Returns a pointer to the section with given name (or NULL if the section doesn't exist).
     453    */
    386454    ConfigFileSection* ConfigFile::getSection(const std::string& section) const
    387455    {
    … …  
    392460    }
    393461
     462    /**
     463        @brief Returns a pointer to the section with given name. If it doesn't exist, the section is created.
     464    */
    394465    ConfigFileSection* ConfigFile::getOrCreateSection(const std::string& section)
    395466    {
    … …  
    403474    }
    404475
     476    /**
     477        @brief Saves the config file if it was updated (or if any of its sections were updated).
     478    */
    405479    void ConfigFile::saveIfUpdated()
    406480    {
    … …  
    442516    SettingsConfigFile* SettingsConfigFile::singletonPtr_s = 0;
    443517
     518    /**
     519        @brief Constructor: Activates the console commands.
     520    */
    444521    SettingsConfigFile::SettingsConfigFile(const std::string& filename)
    445522        : ConfigFile(filename)
    … …  
    452529    }
    453530
     531    /**
     532        @brief Destructor: Deactivates the console commands.
     533    */
    454534    SettingsConfigFile::~SettingsConfigFile()
    455535    {
    … …  
    461541    }
    462542
     543    /**
     544        @brief Loads the config file and updates the @ref ConfigValueContainer "config value containers".
     545    */
    463546    void SettingsConfigFile::load()
    464547    {
    … …  
    467550    }
    468551
     552    /**
     553        @brief Changes the file-name.
     554    */
    469555    void SettingsConfigFile::setFilename(const std::string& filename)
    470556    {
    … …  
    472558    }
    473559
     560    /**
     561        @brief Registers a new @ref ConfigValueContainer "config value container".
     562    */
    474563    void SettingsConfigFile::addConfigValueContainer(ConfigValueContainer* container)
    475564    {
    … …  
    481570    }
    482571
     572    /**
     573        @brief Unregisters a @ref ConfigValueContainer "config value container".
     574    */
    483575    void SettingsConfigFile::removeConfigValueContainer(ConfigValueContainer* container)
    484576    {
    … …  
    500592    }
    501593
     594    /**
     595        @brief Updates all @ref ConfigValueContainer "config value containers".
     596    */
    502597    void SettingsConfigFile::updateConfigValues()
    503598    {
     599        // todo: can this be done more efficiently? looks like some identifiers will be updated multiple times.
     600
    504601        for (ContainerMap::const_iterator it = this->containers_.begin(); it != this->containers_.end(); ++it)
    505602        {
    … …  
    509606    }
    510607
     608    /**
     609        @brief Removes entries and sections from the file that don't exist anymore (i.e. if there's no corresponding @ref ConfigValueContainer "config value container").
     610        @param bCleanComments If true, comments are also removed from the file
     611    */
    511612    void SettingsConfigFile::clean(bool bCleanComments)
    512613    {
    … …  
    558659    }
    559660
     661    /**
     662        @brief Console-command: Changes the value of an entry and stores it the file.
     663
     664        @param section  The section of the config value
     665        @param entry    The name of the config value
     666        @param value    The new value
     667    */
    560668    void SettingsConfigFile::config(const std::string& section, const std::string& entry, const std::string& value)
    561669    {
    … …  
    564672    }
    565673
     674    /**
     675        @brief Console-command: Changes the value of an entry, but doesn't store it in the file (it's only a temporary change).
     676
     677        @param section  The section of the config value
     678        @param entry    The name of the config value
     679        @param value    The new value
     680    */
    566681    void SettingsConfigFile::tconfig(const std::string& section, const std::string& entry, const std::string& value)
    567682    {
    … …  
    570685    }
    571686
     687    /**
     688        @brief Changes the value of an entry, depending on @a function, either by using "set" or "tset"
     689
     690        @param section  The section of the config value
     691        @param entry    The name of the config value
     692        @param value    The new value
     693        @param function The function ("set" or "tset") that will be used to change the value.
     694    */
    572695    bool SettingsConfigFile::configImpl(const std::string& section, const std::string& entry, const std::string& value, bool (ConfigValueContainer::*function)(const MultiType&))
    573696    {
    … …  
    586709    }
    587710
     711    /**
     712        @brief Console-command: Returns the value of a given entry.
     713
     714        @param section  The section of the config value
     715        @param entry    The name of the config value
     716    */
    588717    std::string SettingsConfigFile::getConfig(const std::string& section, const std::string& entry)
    589718    {
    … …  
    611740    ConfigFileManager* ConfigFileManager::singletonPtr_s = 0;
    612741
     742    /// Constructor: Initializes the array of config files with NULL.
    613743    ConfigFileManager::ConfigFileManager()
    614744    {
    … …  
    616746    }
    617747
     748    /// Destructor: Deletes the config files.
    618749    ConfigFileManager::~ConfigFileManager()
    619750    {
    … …  
    623754    }
    624755
     756    /// Defines the file-name for the config file of a given type (settings, calibration, etc.).
    625757    void ConfigFileManager::setFilename(ConfigFileType::Value type, const std::string& filename)
    626758    {
Note: See TracChangeset for help on using the changeset viewer.