Changeset 789 for library/bdm/bdmroot.h

Timestamp:

01/18/10 20:42:46 (14 years ago)

Author:

mido

Message:

libconfig_mex.cpp and libconfig_mex.h added (but that is all is done at the moment)
the documentation of root::to_setting(), root::from_setting() and root::validate() was extended

Files:

• library/bdm/bdmroot.h (modified) (5 diffs)

library/bdm/bdmroot.h

@@ -18 +18 @@
 
 #include "itpp_ext.h"
-#include "base/libconfig/lib/libconfig.h++"
 #include "bdmerror.h"
+
+#ifdef MEX
+        #include "base/libconfig/lib/libconfig.h++"     
+        // TODO DODELAT A NAHRADIT #include "base/libconfig_mex.h"
+#else
+        #include "base/libconfig/lib/libconfig.h++"
+#endif
+
 
 using namespace libconfig;
@@ -26 +33 @@
 
 namespace bdm {
-
-        
-        //! auxiliary function for debugging
-        void UI_DBG (const Setting &S, const string &spc, ostream &out );
+        
+//! auxiliary function for debugging
+void UI_DBG (const Setting &S, const string &spc, ostream &out );
         
 //forward declaration
@@ -54 +60 @@
         int log_level;
 
-        //! It is necessary to allow calling of from_setting and to_setting within the user_info class
+        //! It is necessary to allow calling of from_setting and to_setting within the UI class
         friend class UI;
 
-        //! Read instance properties according the data stored in the Setting structure
-        //! 
-        //! It has to be called only through user_info class, therefore it is protected 
+        /*!     
+        \brief Read instance properties according the data stored in the Setting structure.
+        It has to be called only through UI class, therefore it is protected 
+
+        At the begining of this method, it is obligatory to call
+        the corresponding base::from_setting method. Sometimes, there can be 
+        an exception from this rule. If so, the programmer is encouraged 
+        to describe the reasons for this exception in the documentation in detail.
+        
+        Then, all the configuration     components should be read through the UI mechanism. 
+        Those with UI::SettingPresence set to optional shoud have their defaults fulfilled 
+        within the body of this method.
+
+        For instance, declaring a class \c trunk derived from our #root class, 
+        the implementation of the from_setting method should look like this
+
+        \code
+
+        public trunk : public root {
+
+                anytype xxx, yyy;
+
+                virtual void from_setting ( const Setting &set ) {
+                        root::from_setting( set );
+                        
+                        UI::get ( xxx, set, "xxx", UI::compulsory );
+
+                        if ( !UI::get ( yyy, set, "yyy", UI::optional ) ) {
+                                ... // here, it is necessary to set the default of attribute yyy                                                
+                        }
+
+                        ... // another stuff related to trunk class
+                }
+
+                ... // other members of this class
+        };
+
+        \endcode
+        */
         virtual void from_setting ( const Setting &set ) {
         }
 
-        //! Save all the instance properties into the Setting structure
-        //!
-        //! It has to be called only through user_info class, therefore it is protected 
+        /*!     
+        \brief  Save all the instance properties into the Setting structure.
+        It has to be called only through UI class, therefore it is protected 
+
+        The only obligatory rule concerning the body of this method is to call
+        the corresponding base::to_setting method first.        Sometimes, there can 
+        be an exception from this rule. If so, the programmer is encouraged 
+        to describe the reasons for this exception in the documentation in detail.
+        
+        For instance, declaring
+        a class \c trunk derived from our #root class, the implementation of 
+        the to_setting method should look like this
+
+        \code
+        public trunk : public root {
+
+                anytype xxx;
+
+                virtual void to_setting ( const Setting &set ) {
+                        root::to_setting( set );
+
+                        UI::save ( xxx, set, "xxx" );
+                        
+                        ... // another stuff related directly to trunk class
+
+                }
+
+                ... // other members of this class
+
+        };
+
+        \endcode
+        */
         virtual void to_setting ( Setting &set ) const {
         }
@@ -101 +173 @@
         }
 
-        //! Check that all internal structures has been correctly set-up. Called at the end of from_setting.
+        /*!     
+        \brief  This method checks that all internal structures has been set up correctly.
+
+        It is called automatically after the call of the #from_setting method by the mechanism of the UI class. 
+        However, it can be called in any other situation to assure the correctness of an instance.
+        
+        The only obligatory rule concerning the body of this method is to call
+        the corresponding base::validate method first. Sometimes, there can be 
+        an exception from this rule. If so, the programmer is encouraged 
+        to describe the reasons for this exception in the documentation in detail.      
+        
+        Then, only those checks which are not implemented in the base method 
+        are implemented here. For instance, declaring a class \c trunk derived from our 
+        #root class, the implementation of the method validate should 
+        look like this
+
+        \code
+        public trunk : public root {
+
+                virtual void validate ( ) {
+                        root::validate( );
+
+                        ... // checks related directly to trunk class
+                }
+
+                ... // other members of this class
+
+        };
+
+        \endcode
+
+        */
         virtual void validate() {
         }
@@ -108 +211 @@
         virtual root* _copy() const NOT_IMPLEMENTED(NULL);
         
-
         //! access function
         int _log_level() const {
                 return log_level;
         }
-
 };