Changeset 396 for library/bdm

Timestamp:

06/24/09 13:38:47 (15 years ago)

Author:

mido

Message:

UI documentation almost finished; UIException redesigned and used instead of UI::ui_error function

Location:

library/bdm/base

Files:

• user_info.cpp (modified) (18 diffs)
• user_info.h (modified) (21 diffs)

library/bdm/base/user_info.cpp

@@ -1 +1 @@
 //
-// C++ Implementation: itpp_ext
-//
-// Description:
-//
-//
-// Author: smidl <smidl@utia.cas.cz>, (C) 2008
+// C++ Implementation: user_info.cpp
+//
+// Description: UI (user info) class for loading/saving objects from/to configuration files.
+//
+//
+// Author: smidl <smidl@utia.cas.cz>, (C) 2009
 //
 // Copyright: See COPYING file that comes with this distribution
@@ -120 +120 @@
 }
 
-///////////////////////////// Class UI::SettingResolver /////////////////////////////////////////////
-
-UI::SettingResolver::SettingResolver( const Setting &potential_link )
+///////////////////////////// Class SettingResolver /////////////////////////////////////////////
+
+SettingResolver::SettingResolver( const Setting &potential_link )
         : result( initialize_reference( file, potential_link ) )
 {
 }
 
-const Setting& UI::SettingResolver::initialize_reference(UIFile *&file, const Setting &potential_link)
+const Setting& SettingResolver::initialize_reference(UIFile *&file, const Setting &potential_link)
 {
         file = NULL;
@@ -153 +153 @@
 
     if ( !result->exists( link ) )
-        ui_error( "linked setting was not found", potential_link );
+        throw UIException( "linked setting was not found", potential_link );
 
     return (*result)[link];
 }
 
-UI::SettingResolver::~SettingResolver()
+SettingResolver::~SettingResolver()
 {
     if ( file ) delete file;
@@ -165 +165 @@
 ///////////////////////////// Class UI /////////////////////////////////////////////
 
-void UI::ui_error( string message, const Setting &element )
-{
-    stringstream error_message;
-    error_message << "UI error: " << message << "! Check path """ << element.getPath() << """, source line " << element.getSourceLine() << ".";
-    it_error ( error_message.str() );
+void UI::assert_type( const Setting &element, Setting::Type type )
+{
+        if( element.getType()!=type)
+                throw UIException("wrong setting type", element);
 }
 
@@ -175 +174 @@
 {
     if ( !element.isList())
-        ui_error( "only TypeList elements could be indexed by integers", element );
+        throw UIException( "only TypeList elements could be indexed by integers", element );
 
     if ( element.getLength() <= index )
-        ui_error( "there is not any child with index " + index, element );
+        throw UIException( "there is not any child with index " + index, element );
 
     return element[index];
@@ -186 +185 @@
 {
     if ( !element.isGroup())
-        ui_error( "only TypeGroup elements could be indexed by strings", element );
+        throw UIException( "only TypeGroup elements could be indexed by strings", element );
 
     if ( !element.exists( name ) )
-        ui_error( "there is not any child named """ + name, element );
+        throw UIException( "there is not any child named """ + name, element );
 
     return element[name];
@@ -278 +277 @@
                 else if ( link.result.getLength() == 4 )
                 {
-                ASSERT_UITYPE(link.result[0],TypeString);
+                assert_type(link.result[0],Setting::TypeString);
                         const char* elem1=(const char*)link.result[0];
                         if( (strcmp(elem1, "matrix") ))
-                                ui_error( "the setting supposed to represent a matrix element has wrong syntax", link.result );
+                                throw UIException( "the setting supposed to represent a matrix element has wrong syntax", link.result );
 
                         data_offset = 1;
                 }
                 else
-                        ui_error( "the setting supposed to represent a matrix element has wrong syntax", link.result );
+                        throw UIException( "the setting supposed to represent a matrix element has wrong syntax", link.result );
 
         Setting &rows_setting = link.result[0 + data_offset];
@@ -292 +291 @@
         Setting &elements = link.result[2 + data_offset];
 
-        ASSERT_UITYPE(cols_setting,TypeInt);
-        ASSERT_UITYPE(rows_setting,TypeInt);
-        ASSERT_UITYPE(elements,TypeArray);
+        assert_type(cols_setting,Setting::TypeInt);
+        assert_type(rows_setting,Setting::TypeInt);
+        assert_type(elements,Setting::TypeArray);
 
         int cols = cols_setting;
@@ -300 +299 @@
 
         if ( cols < 0 | rows < 0 )
-            ui_error( "the dimensions of a matrix has to be non-negative", link.result );
+            throw UIException( "the dimensions of a matrix has to be non-negative", link.result );
 
         if ( elements.getLength() != cols * rows )
-            ui_error( "the count of the matrix elements is incompatible with matrix dimension", elements );
+            throw UIException( "the count of the matrix elements is incompatible with matrix dimension", elements );
 
         matrix.set_size( rows, cols );
@@ -311 +310 @@
 
         if ( !elements[0].isNumber() )
-            ui_error( "matrix elements have to be numbers", elements[0] );
+            throw UIException( "matrix elements have to be numbers", elements[0] );
 
         // build matrix row-wise
@@ -321 +320 @@
     }
 
-    ui_error( "only numeric types or TypeList are supported as matrix values", link.result );
-}
-
-void UI::from_setting( ivec &vector, const Setting &element )
+    throw UIException( "only numeric types or TypeList are supported as matrix values", link.result );
+}
+
+void UI::from_setting( vec &vector, const Setting &element )
 {
     const SettingResolver link( element );
@@ -330 +329 @@
     if ( link.result.isNumber() )
     {
-  //      ASSERT_UITYPE(link.result,TypeInt);
         vector.set_length( 1 );
         vector(0) = link.result;
@@ -342 +340 @@
 
         if ( matrix.cols() != 1 & matrix.rows() !=1)
-                        ui_error( "the vector length is invalid, it seems to be rather a matrix", link.result );
+                        throw UIException( "the vector length is invalid, it seems to be rather a matrix", link.result );
 
         int len = matrix.rows() * matrix.cols();
         vector.set_length ( len );
         if ( len == 0 ) return;
-
-                Setting &elements = link.result[2];
-        // ASSERT_UITYPE(elements[0],TypeInt); -- spolehame an autoconvert
 
         if ( matrix.cols() == 1 )
@@ -358 +353 @@
                                 vector(i) = matrix(0,i);
         return;
-
     }
 
@@ -367 +361 @@
         if ( len == 0 ) return;
 
-        ASSERT_UITYPE(link.result[0],TypeInt);
-        for ( int i=0; i < len; i++ )
-            vector(i) = link.result[i];
-        return;
-    }
-
-    ui_error( "only numeric types, TypeArray or TypeList are supported as vector values", link.result );
-}
-
-void UI::from_setting( vec &vector, const Setting &element )
-{
-    const SettingResolver link( element );
-
-    if ( link.result.isNumber() )
-    {
-        vector.set_length( 1 );
-        vector(0) = link.result;
-        return;
-    }
-
-    if ( link.result.isList() )
-    {
-                mat matrix;
-                from_setting( matrix, link.result );
-
-        if ( matrix.cols() != 1 & matrix.rows() !=1)
-                        ui_error( "the vector length is invalid, it seems to be rather a matrix", link.result );
-
-        int len = matrix.rows() * matrix.cols();
-        vector.set_length ( len );
-        if ( len == 0 ) return;
-
-        if ( matrix.cols() == 1 )
-                        for ( int i=0; i<len; i++ )
-                                vector(i) = matrix(i,0);
-                else
-                        for ( int i=0; i<len; i++ )
-                                vector(i) = matrix(0,i);
-        return;
-    }
-
-    if ( link.result.isArray() )
-    {
-        int len = link.result.getLength();
-        vector.set_length( len );
-        if ( len == 0 ) return;
-
         if ( !link.result[0].isNumber())
-            ui_error("a vector element has to be a number", link.result[0]);
+            throw UIException("a vector element has to be a number", link.result[0]);
 
         for ( int i=0; i < len; i++ ) 
@@ -423 +370 @@
     }
 
-    ui_error( "only numeric types, TypeArray or TypeList are supported as vector values", link.result );
+    throw UIException( "only numeric types, TypeArray or TypeList are supported as vector values", link.result );
+}
+
+void UI::from_setting( ivec &vector, const Setting &element )
+{
+        vec double_vector;
+        from_setting( double_vector, element ); 
+    int len = double_vector.length();
+    vector.set_length ( len );
+        for( int i = 0; i< len; i++ )
+                vector(i) = (int) double_vector(i);
 }
 
 void UI::from_setting( string &str, const Setting &element )
 {
-    ASSERT_UITYPE(element,TypeString);
+    assert_type(element,Setting::TypeString);
     str = (const char*) element;
 }
@@ -434 +391 @@
 void UI::from_setting( int &integer, const Setting &element )
 {
-    ASSERT_UITYPE(element,TypeInt);
+    assert_type(element,Setting::TypeInt);
     integer = element;
 }
@@ -440 +397 @@
 void UI::from_setting( double &real, const Setting &element )
 {
-    ASSERT_UITYPE(element,TypeFloat);
+    assert_type(element,Setting::TypeFloat);
     real = element;
 }

library/bdm/base/user_info.h

@@ +1 @@
+/*!
+  \file
+  \brief UI (user info) class for loading/saving objects from/to configuration files.  
+  It is designed over with an use of 'libconfig � C/C++ Configuration File Library'
+  \author Vaclav Smidl.
+
+  -----------------------------------
+  BDM++ - C++ library for Bayesian Decision Making under Uncertainty
+
+  Using IT++ for numerical operations
+  -----------------------------------
+*/
+
 #ifndef USER_INFO_H
 #define USER_INFO_H
@@ -6 +19 @@
 #include <typeinfo>
 #include <map>
+#include <stdexcept>
 
 #include "libconfig/libconfig.h++"
@@ -11 +25 @@
 #include "itpp/itbase.h"
 
-#include <stdexcept>
 
 using std::string;
@@ -22 +35 @@
 /*!
   \def UIREGISTER(class_name)
-  Macro for registration of class into map of UserInfos -- registered class is scriptable 
-
-  TODO napsat i to, ze UIREG musi byt v hacku..
+  \brief Macro for registration of class into map of user-infos, registered class is scriptable using UI static methods
+  
+  Argument \a class_name has to be a descendant of root class and also, it has to have parameterless constructor prepared.
+  This macro should be used in header file, immediately after a class declaration.
+  
+  \sa TODO MODUL  
 */
 #ifndef BDMLIB 
-#define UIREGISTER(class_name) template<> const ParticularUI<class_name>& ParticularUI<class_name>::ui = ParticularUI<class_name>(#class_name) 
+        #define UIREGISTER(class_name) template<> const ParticularUI<class_name>& ParticularUI<class_name>::factory = ParticularUI<class_name>(#class_name) 
 #else
-#define UIREGISTER(class_name)
+        #define UIREGISTER(class_name)
 #endif
 
-//!  macro assertting that the setting SET is of the SettingType TYPE
-#define ASSERT_UITYPE(SET,TYPE) it_assert_debug(SET.getType()==Setting::TYPE, string("Wrong setting type, see input path \"")+string(SET.getPath())+string("\""))
-
-//! exception used in UI::build if it fails it can be caught and handled - see merger_mex.h
-class UIbuildException : public std::invalid_argument {
-        public:
-                UIbuildException() : std::invalid_argument("class name") { }
+//! Exception prepared for reporting user-info errors which are always related to some concrete Setting path
+class UIException : public std::exception
+{
+private:
+        //! Error message
+        const string message;
+
+public:
+        //! Use this constructor when you can pass the problematical Setting as a parameter
+        UIException( const string &message, const Setting &element  ) 
+                : message( "UI error: " + message + ". Check path \"" + string(element.getPath()) + "\"." )
+        {
+        }
+
+        //! This constructor is for other occasions, when only path of problematical Setting is known
+        UIException( const string &message, const string &path  ) 
+                : message( "UI error: " + message + "! Check path \"" + path + "\"." )
+        {
+        }
+
+        //! Overriden method for reporting an error message
+        virtual const char* what() const throw()
+        {
+                return message.c_str();
+        }
 };
+
 
 /*!
@@ -66 +101 @@
 {
 public:
-        //! create empty file instance prepared to store Settings
+        //! Create empty file instance prepared to store Settings
         UIFile();
 
-        //! creates instance and fills it from the configuration file file_name
+        //! Creates instance and fills it from the configuration file file_name
         UIFile( const string &file_name );
 
-        //! save all the stored Settings into the configuration file file_name
+        //! Save all the stored Settings into the configuration file file_name
         void save(const string &file_name);
 
-        //! this operator allows the ability of substituting Setting parameter by UIFile instance
+        //! This operator allows the ability of substituting Setting parameter by UIFile instance
         operator Setting&();
 };
 
-
+/*!
+@brief This class serves to expand links used within configuration files. 
+
+Value of any type but string can be linked to some other value of the same type
+defined elsewhere in the current configuration file or even in some different
+configuration file. 
+
+Link have three parts, \<name\> : \<path\> \<\@filename\>. Field \<name\> contains the 
+name of the new setting, \<path\> is the relative path to the referenced setting, which
+has to be taken from the %root Setting element. The last part \<\@filename\> is optional, 
+it contains filename in the case the link should refer to a variable stored in a different
+file. From the previous part \<path\>, it has to be separated by '@'.
+
+\code
+    ...
+        jardovo : 
+        {
+          class = "Car";
+          year = 1992;
+          manufacturer = "liaz";
+          kilometers = 1555000;
+        };
+        ondrejovo : 
+        {
+          class = "Bike";
+          year = 1996;
+          manufacturer = "author";
+          electricLights = true;
+          matr = ( 2, 2, [ 1.0, 0.0, 0.0, 1.0 ] );
+        };
+        
+        #this is the example of local link to another mean of transport 
+        elisky = "jardovo";
+
+        ...
+
+        # and this link is external link pointing to file "other_cars.cfg" stored in the
+        # same directory, in that file, it refers to the local Setting "magic_cars.skubankovo"
+        kati = "magic_cars.skubankovo@other_cars.cfg";
+
+    ...
+\endcode
+
+When you want to expand a possible linked setting "element" within your code, it has to be treated this way:
+
+\code
+        ...
+
+        const SettingResolver link( element );
+
+        ...
+
+        int len = link.result.getLength();
+
+        ...
+\endcode
+
+The whole point is that a resolved link (class member #result, i.e., "link.result" in the previous example) could point 
+into a different configuration file. In that case there has to be an UIFile instance managing reading from this
+file. As the libconfig::Config deletes all its Settings when dealocated, UIFile must not be dealocated until all 
+the necessary operation on the linked Setting are finished (otherwise, the link #result would be invalid just after 
+the UIFile dealocation). And that is exactly the mechanism implemented within SettingResolver class. It assures, 
+that the #result Setting reference is valid within the scope of SettingResolver instance.
+ */
+class SettingResolver : root
+{
+private:
+        //! If necessary, this pointer stores an addres of an opened UIFile, else it equals NULL
+        UIFile *file;
+
+        //! This method initialize #result reference, i.e., it executes the main code of SettingResolver class
+        //!
+        //! This code could be also located directly in constructor. The only reason why we made this 
+        //! method is the keyword 'const' within the declaration of #result reference . Such a reference
+        //! have to be intialized before any other constructor command, exactly in the way it is implemented now.
+        const Setting &initialize_reference( UIFile* &file, const Setting &potential_link);
+
+public:
+        //! Reference to a resolved link or to the original Setting in the case it does not contain a link
+        const Setting &result;
+
+        //! If potential_link contains a link to some other setting, it is resolved here. Anyway, the Setting reference #result is prepared for use.
+        SettingResolver( const Setting &potential_link );
+        
+        //! An opened UIFile file is closed here if necessary.
+        ~SettingResolver();             
+};
 
 /*!
@@ -94 +215 @@
         //! 
         //! The key property of this class is that it initilaize the internal map immediately
-        //! when it is used for a first time. Therefore, we do not have to care about the 
-        //! order of calls to UIREGISTER macro, which operates with both these mappings.
+        //! when it is used for a first time. Therefore, we do not have to care about initialization 
+        //! during a call of UIREGISTER macro operating with both these mappings.
         class MappedUI
         {
@@ -105 +226 @@
                 typedef map< const type_info * const, const string > TypeInfoToStringMap;
 
-                //! immediately initialized instance of type StringToUIMap
+                //! Immediately initialized instance of type StringToUIMap
                 static StringToUIMap& mapped_strings();
 
-                //! immediately initialized instance of type TypeInfoToStringMap
+                //! Immediately initialized instance of type TypeInfoToStringMap
                 static TypeInfoToStringMap& mapped_type_infos();
 
-                //! method for reporting a error when an attempt to operate with an unregistered class occures
+                //! Method for reporting a error when an attempt to operate with an unregistered class occures
                 static void unregistered_class_error( const string &unregistered_class_name );
 
         public:
-                //! add a pair key-userinfo into the internal map
+                //! Add a pair key-userinfo into the internal map
                 static void add_class( const string &class_name, const type_info * const class_type_info, const UI* const ui );
 
-                //! search for an userinfo related to the passed class name within the internal map
+                //! Search for an userinfo related to the passed class name within the internal map
                 static const UI& retrieve_ui( const string &class_name );
 
-                //! search for an class name related to the passed type_info within the internal map
+                //! Search for an class name related to the passed type_info within the internal map
                 static const string& retrieve_class_name( const type_info* const class_type_info );
         };
 
+        //! Function assertting that the setting element is of the SettingType type
+        static void assert_type( const Setting &element, Setting::Type type);
+
         //! Method assembling a typeless instance, it is implemented in descendant class ParticularUI<T>
         virtual root* new_instance() const = 0;
@@ -134 +258 @@
         static const Setting& to_child_setting( const Setting &element, const string &name );
 
-        //! This methods converts a Setting into a matrix 
+        //! This method converts a Setting into a matrix 
         static void from_setting( mat& matrix, const Setting &element );        
-        //! This methods converts a Setting into an integer vector
+        //! This method converts a Setting into an integer vector
         static void from_setting( ivec &vector, const Setting &element );
-        //! This methods converts a Setting into a string
+        //! This method converts a Setting into a string
         static void from_setting( string &str, const Setting &element );
-        //! This methods converts a Setting into a real vector
+        //! This method converts a Setting into a real vector
         static void from_setting( vec &vector, const Setting &element );
-        //! This methods converts a Setting into a integer scalar 
+        //! This method converts a Setting into a integer scalar 
         static void from_setting( int &integer, const Setting &element );
-        //! This methods converts a Setting into a real scalar 
+        //! This method converts a Setting into a real scalar 
         static void from_setting( double &real, const Setting &element );
-        //! This methods converts a Setting into a class T descendant
+        //! This method converts a Setting into a class T descendant
         template<class T> static void from_setting( T* &instance, const Setting &element )
         {                       
                 const SettingResolver link( element );
-
-                ASSERT_UITYPE(link.result,TypeGroup);
-
-                // we get a velue stored in the "class" attribute 
+                assert_type(link.result,Setting::TypeGroup);
+
+                // we get a value stored in the "class" attribute 
                 string class_name;
                 if( !link.result.lookupValue( "class", class_name ) )
-                        ui_error( "the obligatory ""class"" identifier is missing", link.result );
+                        throw UIException( "the obligatory \"class\" identifier is missing", link.result );
         
                 // then we find a user-info related to this type
@@ -163 +286 @@
                 root* typeless_instance = related_UI.new_instance();
 
-                instance = NULL;
-                //try catch does not work!!!
                 instance = dynamic_cast<T*>(typeless_instance);
-                if (!instance){
-                        throw UIbuildException();
-                }
-//              catch(...)
-//              {
-                        // TODO pouzit ui_error? 
-//                      it_error ( "UI error: class " + class_name + " is not a descendant of the desired output class. Try to call the UI::build function with a different type parameter." );
-//              }
-//              
+                if (!instance)
+                        throw UIException( "class " + class_name + " is not a descendant of the desired output class. Try to call the UI::build<T> function with a different type parameter.", link.result );
+                
                 try
                 {
@@ -181 +296 @@
                 catch(SettingException xcptn)
                 {
-                        // TODO pouzit ui_error? 
-                        it_error ( "UI error: the method " + class_name + ".from_setting(Setting&) has thrown an exception when parsing the setting " + xcptn.getPath() + ". Try to correct this method." );
+                        throw UIException( "the method " + class_name + ".from_setting(Setting&) has thrown an SettingException. Try to correct this method", xcptn.getPath());
                 }
         }       
 
-        //! This methods converts a Setting into a new templated array , 
-        // TODO efektivne jen pro vect, mat a string, pro dalsi je nutne pridat from_setting metodu.. ale to asi necceme
+        //! This methods converts a Setting into a new templated array of type Array<T>
         template<class T> static void from_setting( Array<T> &array_to_load, const Setting &element )
         {
                 const SettingResolver link( element );
 
-                ASSERT_UITYPE(link.result,TypeList);
+                assert_type(link.result,Setting::TypeList);
 
                 int len = link.result.getLength();
@@ -202 +315 @@
         }
 
-        //! Method for reporting user-info errors related to some concrete Setting
-        static void ui_error( string message, const Setting &element );
-
 protected:
         //! Default constructor for internal use only, see \sa ParticularUI<T>
@@ -214 +324 @@
 public: 
 
-        /*!
-        @brief This class serves to expand links used in configuration file. 
-
-        TODO - napsat co dela, a hlavne proc je to takhle implementovany.. otevreny soubor!
-
-        ABSOLUTE PATH.. 
-
-        Firstly, save some user-infos into the new UIFile instance. Then, 
-        call the save method with a filename as its only argument:
-
-        \code
-                CAudi audi;
-                UIFile file;
-                UI::save( audi, file, "TT");
-                file.save("cars.cfg");
-        \endcode
-
-        */
-        class SettingResolver   
-        {
-        private:
-                //! If necessary, this pointer stores an addres of an opened UIFile, else it equals NULL
-                UIFile *file;
-
-                //! This method initialize result reference, i.e., it executes the main code of SettingResolver class
-                //!
-                //! This code could be also located directly in constructor. The only reason why we made this 
-                //! method is the keyword 'const' within the declaration of result reference (TODO funguje odkaz?). Such a reference
-                //! have to be intialized before any other constructor command, exactly in the way it is implemented now.
-                const Setting &initialize_reference( UIFile* &file, const Setting &potential_link);
-
-        public:
-                //! Reference to a resolved link or to the original Setting in the case it does not contain a link
-                const Setting &result;
-
-                //! If potential_link contains a link to some other setting, it is resolved here. Anyway, the Setting reference result is prepared for use.
-                SettingResolver( const Setting &potential_link );
-                
-                //! An opened UIFile file is closed here if necessary.
-                ~SettingResolver();             
-        };
-
-        //TODO
-        //! \name Initialization of bdm::root descendant classes according the values stored in a Setting variable
+        //! \name Initialization of classes 
         //!@{
-        //! Return value is by the second argument since it type checking via \c dynamic_cast.
-        template<class T> static T* build( const Setting &element, const int index )
-        {
-                T* instance;
-                from_setting<T>( instance, to_child_setting( element, index ) );
-                return instance;
-        }
-        //! VS: addition for root elements
-        template<class T> static T* build( const Setting &element )
-        {
-                T* instance;
-                from_setting<T>( instance,  element );
-                return instance;
-        }
-
+        //! The type T has to be a root descendant class
+
+        //! The new instance of type T* is constructed and initialized with values stored in the Setting element[name]
         template<class T> static T* build( const Setting &element, const string &name )
         {                       
@@ -280 +335 @@
                 return instance;
         }
+        //! The new instance of type T* is constructed and initialized with values stored in the Setting element[index]
+        template<class T> static T* build( const Setting &element, const int index )
+        {
+                T* instance;
+                from_setting<T>( instance, to_child_setting( element, index ) );
+                return instance;
+        }
+        //! The new instance of type T* is constructed and initialized with values stored in the Setting element
+        template<class T> static T* build( const Setting &element )
+        {
+                T* instance;
+                from_setting<T>( instance,  element );
+                return instance;
+        }
         //!@}
 
-        //! \name Initialization of structures according the values stored in a Setting variable - TODO VYCET?!
+        //! \name Initialization of structures 
         //!@{
-        //! This methods tries to build a new double matrix 
+        //! The type T has to be int, double, string, vec, ivec or mat.
+
+        //! The existing instance of type T is initialized with values stored in the Setting element[name]
         template<class T> static void get( T &instance, const Setting &element, const string &name )
         {
@@ -290 +361 @@
         }
 
-        //! This methods tries to build a new double matrix 
+        //! The existing instance of type T is initialized with values stored in the Setting element[index] 
         template<class T> static void get( T &instance, const Setting &element, const int index )
         {
@@ -296 +367 @@
         }
 
-        //! This methods tries to build a new double matrix 
+        //! The existing instance of type T is initialized with values stored in the Setting element directly
         template<class T> static void get( T &instance, const Setting &element  )
         {
                 from_setting( instance, element );
         }
-
-        //! This methods tries to build a new double matrix 
+        //!@}
+
+        //! \name Initialization of arrays Array<T>
+        //!@{
+        //! The type T has to be int, double, string, vec, ivec or mat, or pointer to any root descendant.
+
+        //! The existing array of type T is initialized with values stored in the Setting element[name]
         template<class T> static void get( Array<T> &array_to_load, const Setting &element, const string &name )
         {
@@ -308 +384 @@
         }
 
-        //! This methods tries to build a new double matrix 
+        //! The existing array of type T is initialized with values stored in the Setting element[index]
         template<class T> static void get( Array<T> &array_to_load, const Setting &element, const int index )
         {
@@ -314 +390 @@
         }
 
-        //! This methods tries to build a new double matrix 
+        //! The existing array of type T is initialized with values stored in the Setting element
         template<class T> static void get( Array<T> &array_to_load, const Setting &element  )
         {
@@ -321 +397 @@
         //!@}
 
+        //! \name Serialization of objects and structures into a new Setting 
+        //!@{
+        //! The new child Setting can be accessed either by its name - if some name is passed as a parameter -
+        //! or by its integer index. In that case, the new element is added at the very end of the current list of child Settings.
+
+        //! A root descendant instance is stored in the new child Setting appended to the passed element
         template< class T> static void save( const T * const instance, Setting &element, const string &name = "")
         {
@@ -338 +420 @@
                 catch(SettingException xcptn)
                 {
-                        it_error ( "UI error: the method " + class_name + ".to_setting(Setting&) has thrown an exception when filling the setting " + xcptn.getPath() + ". Try to correct this method." );
+                        throw UIException( "the method " + class_name + ".to_setting(Setting&) has thrown an SettingException. Try to correct this method", xcptn.getPath());
                 }       
         }
 
-        //! This methods tries to save a double vec 
+        //! An Array<T> instance is stored in the new child Setting appended to the passed element
         template<class T> static void save( const Array<T> &array_to_save, Setting &element, const string &name = "" )
         {
-                ASSERT_UITYPE(element,TypeGroup);
+                assert_type(element,Setting::TypeGroup);
                 Setting &list = (name == "") ? element.add( Setting::TypeList )                                                 
                                                                          : element.add( name, Setting::TypeList );              
@@ -352 +434 @@
         }
 
-
-        //! This methods tries to save a double matrix 
+        //! A matrix(of type mat) is stored in the new child Setting appended to the passed element
         static void save( const mat &matrix, Setting &element, const string &name = "" );
 
-        //! This methods tries to save a double vec 
+        //! An integer vector (of type ivec) is stored in the new child Setting appended to the passed element
         static void save( const ivec &vec, Setting &element, const string &name = "" );
         
+        //! A double vector (of type vec) is stored in the new child Setting appended to the passed element
         static void save( const vec &vector, Setting &element, const string &name = "" );
-        //! This methods tries to save a double vec 
+
+        //! A string is stored in the new child Setting appended to the passed element
         static void save( const string &str, Setting &element, const string &name = "" );
 
+        //! An integer is stored in the new child Setting appended to the passed element
         static void save( const int &integer, Setting &element, const string &name = "" );
 
+        //! A double is stored in the new child Setting appended to the passed element
         static void save( const double &real, Setting &element, const string &name = "" );      
+        //!@}
 
 };
 
 
-/*!
-@brief The main userinfo template class. You should derive this class whenever you need 
-a new userinfo of a class which is compound from smaller elements (all having its
-own userinfo class prepared).
-*/
+//! The only UI descendant class which is not intended for direct use. It should be accessed within the ::UIREGISTER macro only.
 template<typename T> class ParticularUI : private UI
 {
-        public:
-
-        //! default constructor, which is intentionally declared as private
+private:
+        //! Default constructor, which is intentionally declared as private
         ParticularUI<T>( const string &class_name) : UI( class_name, &typeid(T) ) 
-        {       cout << class_name << endl;
-        };
-
-        //! the only instance of this class (each type T has its own instance)
-        //! which is used as a factory for processing related UI
-        static const ParticularUI<T>& ui;       
-
+        {};
+
+public:
+        //! The only instance of this class (each type T has its own instance) which is used as a factory for processing related UI
+        static const ParticularUI<T>& factory;  
+
+        //! A method returning a brand new instance of class T, this method is the reason why there have to be a parameterless construcotor in class T
         root* new_instance() const
         {
@@ -394 +475 @@
 };
 
-
-
-
 }
 
-/*! Recursive build of objects defined in the same file
-
-\code 
-{type="internal";
-path="system.profile.[0]";    // Path from the root 
-};
-\endcode
- */
-
-
-
-/*! Recursive build of objects defined in external file
-
-\code 
-{type="external";
-filename="my_file.cfg";       // name of file from which to read
-path="system.profile.[0]";    // Path in the external file
-};
-\endcode
-/
-
-*/
-
 #endif // #ifndef USER_INFO_H