git-svn-id: file:///home/svn/opt_utilities@48 ed2142bd-67ad-457f-ba7c-d818d4011675

6 files changed, 434 insertions, 47 deletions

diff --git a/core/fitter.hpp b/core/fitter.hpp
index 87e316e..2dff97b 100644
--- a/core/fitter.hpp
+++ b/core/fitter.hpp
@@ -897,6 +897,7 @@ namespace opt_utilities
       return do_eval(x,reform_param(p));

     }

 

+  private:

     virtual Ty do_eval(const Tx& x,const Tp& p)=0;

 

   private:

@@ -908,21 +909,35 @@ namespace opt_utilities
   };

 

 

-

+  /**

+     class to perform the model fitting

+     \tparam Ty the type of the model return type

+     \tparam Tx the type of the model self-var

+     \tparam Tp the type of the model param

+     \tparam Ts statistic type

+     \tparam Tstr the type of string used

+   */

   template<typename Ty,typename Tx,typename Tp,typename Ts=Ty,typename Tstr=std::string>

   class fitter

   {

-  public:

+  private:

     model<Ty,Tx,Tp,Tstr>* p_model;

     statistic<Ty,Tx,Tp,Ts,Tstr>* p_statistic;

     data_set<Ty,Tx>* p_data_set;

     optimizer<Ts,Tp> optengine;

   public:

+    

+    /**

+       default construct function

+    */

     fitter()

       :p_model(0),p_statistic(0),p_data_set(0),optengine()

     {}

 

     

+    /**

+       copy construct function

+     */

     fitter(const fitter& rhs)

       :p_model(0),p_statistic(0),p_data_set(0),optengine()

     {

@@ -942,6 +957,10 @@ namespace opt_utilities
       optengine=rhs.optengine;

     }

     

+

+    /**

+       assignment operator

+     */

     fitter& operator=(const fitter& rhs)

     {

       if(this==&rhs)

@@ -964,6 +983,10 @@ namespace opt_utilities
       return *this;

     }

     

+

+    /**

+       destruct function

+     */

     virtual ~fitter()

     {

       if(p_model!=0)

@@ -984,6 +1007,9 @@ namespace opt_utilities
     }

     

 

+    /**

+       evaluate the model

+     */

     Ty eval_model(const Tx& x,const Tp& p)

     {

       if(p_model==0)

@@ -1004,6 +1030,11 @@ namespace opt_utilities
     

 

   public:

+

+    /**

+       set the model

+       \param m model to be used

+     */

     void set_model(const model<Ty,Tx,Tp,Tstr>& m)

     {

       if(p_model!=0)

@@ -1015,12 +1046,12 @@ namespace opt_utilities
       //p_model=&m;

       //  current_param.resize(m.get_num_params());

     }

-    /*

-    void set(const model<Ty,Tx,Tp>& m)

-    {

-      set_model(m);

-    }

-    */

+

+

+    /**

+       set the statistic (e.g., chi square, least square c-statistic etc.)

+       \param s statistic to be used

+     */

     void set_statistic(const statistic<Ty,Tx,Tp,Ts,Tstr>& s)

     {

       if(p_statistic!=0)

@@ -1032,13 +1063,11 @@ namespace opt_utilities
       //p_statistic=&s;

       p_statistic->set_fitter(*this);

     }

-    /*

-    void set(const statistic<Ty,Tx,Tp>& s)

-    {

-      set_statistic(s);

-    }

-    */

 

+    /**

+       set parameter modifier

+       \param pm parameter modifier to be used

+     */

     void set_param_modifier(const param_modifier<Ty,Tx,Tp,Tstr>& pm)

     {

       if(p_model==0)

@@ -1048,6 +1077,9 @@ namespace opt_utilities
       p_model->set_param_modifier(pm);

     }

 

+    /**

+       clear the param modifier

+    */

     void set_param_modifier()

     {

       if(p_model==0)

@@ -1057,6 +1089,11 @@ namespace opt_utilities
       p_model->set_param_modifier();

     }

 

+

+    /**

+       Get the inner kept param modifier

+       \return the reference of param_modifier

+     */

     param_modifier<Ty,Tx,Tp,Tstr>& get_param_modifier()

     {

       if(p_model==0)

@@ -1066,6 +1103,11 @@ namespace opt_utilities
       return p_model->get_param_modifier();

     }

 

+    /**

+       report the status of a parameter

+       \param s the name of a parameter

+       \return string used to describe the parameter

+     */

     Tstr report_param_status(const Tstr& s)const

     {

       if(p_model==0)

@@ -1075,11 +1117,9 @@ namespace opt_utilities
       return p_model->report_param_status(s);

     }

     

-    /*

-    void set(const param_modifier<Ty,Tx,Tp>& pm)

-    {

-      set_param_modifier(pm);

-    }

+    /**

+       load the data set

+       \param da a data set

     */

     void load_data(const data_set<Ty,Tx>& da)

     {

@@ -1095,6 +1135,11 @@ namespace opt_utilities
 	}

     }

 	

+

+    /**

+       get the data set that have been loaded

+       \return the const reference of inner data_set

+     */

     const data_set<Ty,Tx>& get_data_set()const

     {

       if(p_data_set==0)

@@ -1104,6 +1149,10 @@ namespace opt_utilities
       return *(this->p_data_set);

     }

 

+    /**

+       Get the model used

+       \return the reference of model used

+     */

     model<Ty,Tx,Tp,Tstr>& get_model()

     {

       if(p_model==0)

@@ -1113,6 +1162,10 @@ namespace opt_utilities
       return *(this->p_model);

     }

 

+    /**

+       Get the statistic used

+       \return the reference of the statistic used

+     */

     statistic<Ty,Tx,Tp,Ts,Tstr>& get_statistic()

     {

       if(p_statistic==0)

@@ -1121,7 +1174,11 @@ namespace opt_utilities
 	}

       return *(this->p_statistic);

     }

-

+    

+    /**

+       Get the optimization method that used

+       \return the reference of the opt_method

+     */

     opt_method<Ts,Tp>& get_method()

     {

       return optengine.method();

@@ -1129,6 +1186,11 @@ namespace opt_utilities
     

 

   public:

+    /**

+       set the value of a parameter

+       \param pname the name of the parameter

+       \param v the value of the parameter

+    */

     void set_param_value(const Tstr& pname,

 			 const typename element_type_trait<Tp>::element_type& v)

     {

@@ -1139,6 +1201,11 @@ namespace opt_utilities
       p_model->set_param_value(pname,v);

     }

 

+    /**

+       set the lower limit of a parameter

+       \param pname the name of the parameter

+       \param v the lower limit of the parameter       

+     */

     void set_param_lower_limit(const Tstr& pname,

 			       const typename element_type_trait<Tp>::element_type& v)

     {

@@ -1149,6 +1216,11 @@ namespace opt_utilities
       p_model->set_param_lower_limit(pname,v);

     }

 

+    /**

+       set the upper limit of a parameter

+       \param pname the name of the parameter

+       \param v the upper limit of the parameter       

+     */

     void set_param_upper_limit(const Tstr& pname,

 			       const typename element_type_trait<Tp>::element_type& v)

     {

@@ -1160,6 +1232,11 @@ namespace opt_utilities
     }

     

 

+    /**

+       set the values of all parameters

+       \param param the vector containing the value of all parameters

+     */

+

     void set_param_value(const Tp& param)

     {

       if(p_model==0)

@@ -1169,6 +1246,10 @@ namespace opt_utilities
       p_model->set_param_value(param);

     }

 

+    /**

+       set the lower limits of all parameters

+       \param param the vector containing the lower limits of all parameters

+    */

     void set_param_lower_limit(const Tp& param)

     {

       if(p_model==0)

@@ -1178,6 +1259,10 @@ namespace opt_utilities
       p_model->set_param_lower_limit(param);

     }

 

+    /**

+       set the upper limits of all parameters

+       \param param the vector containing the upper limits of all parameters

+    */

     void set_param_upper_limit(const Tp& param)

     {

       if(p_model==0)

@@ -1187,6 +1272,12 @@ namespace opt_utilities
       p_model->set_param_upper_limit(param);

     }

 

+

+    /**

+       get the parameter value

+       \param pname the name of the parameter

+       \return the value of the parameter

+     */

     typename element_type_trait<Tp>::element_type get_param_value(const Tstr& pname)const

     {

       if(p_model==0)

@@ -1196,6 +1287,11 @@ namespace opt_utilities
       return p_model->get_param_info(pname).get_value();

     }

 

+    /**

+       get the lower limit of a parameter

+       \param pname the name of a parameter

+       \return the lower limit of a parameter

+     */

     typename element_type_trait<Tp>::element_type get_param_lower_limit(const Tstr& pname)const

     {

       if(p_model==0)

@@ -1205,6 +1301,11 @@ namespace opt_utilities
       return p_model->get_param_info(pname).get_lower_limit();

     }

     

+    /**

+       get the upper limit of a parameter

+       \param pname the name of a parameter

+       \return the upper limit of a parameter

+     */

     typename element_type_trait<Tp>::element_type get_param_upper_limit(const Tstr& pname)const

     {

       if(p_model==0)

@@ -1215,7 +1316,11 @@ namespace opt_utilities
     }

 

     

-

+    /**

+       get the param_info of a parameter

+       \param pname the name of the parameter

+       \return the const reference of a param_info object

+     */

     const param_info<Tp,Tstr>& get_param_info(const Tstr& pname)const

     {

       if(p_model==0)

@@ -1224,7 +1329,12 @@ namespace opt_utilities
 	}

       return p_model->get_param_info(pname);

     }

-

+    

+    /**

+       get the param_info of a parameter by its order

+       \param n the order of the parameter

+       \return the const reference of a param_info object

+     */

     const param_info<Tp,Tstr>& get_param_info(size_t n)const

     {

       if(p_model==0)

@@ -1234,6 +1344,11 @@ namespace opt_utilities
       return p_model->get_param_info(n);

     }

 

+    /**

+       get the order of a parameter by its name

+       \param pname the name of the parameter

+       \return the order of the parameter

+     */

     size_t get_param_order(const Tstr& pname)const

     {

       if(p_model==0)

@@ -1243,6 +1358,10 @@ namespace opt_utilities
       return p_model->get_param_order(pname);

     }

 

+    /**

+       get the number of parameters

+       \return the number of parameters

+     */

     size_t get_num_params()const

     {

       if(p_model==0)

@@ -1252,6 +1371,10 @@ namespace opt_utilities
       return p_model->get_num_params();

     }

 

+    /**

+       get all params

+       \return the vector containing the values of all parameters

+     */

     Tp get_all_params()const

     {

       if(p_model==0)

@@ -1262,22 +1385,29 @@ namespace opt_utilities
       return p_model->get_all_params();

     }

 

+    /**

+       set the optimization method used to perform the model fitting

+       \param pm the opt_method to be used

+    */

     void set_method(const opt_method<Ts,Tp>& pm)

     {

       //assert(p_optimizer!=0);

       optengine.set_opt_method(pm);

     }

-    /*

-    void set(const opt_method<Ty,Tp>& pm)

-    {

-      set_method(pm);

-    }

-    */

+

+    /**

+       set the precision

+       \param y the precision

+     */

     void set_precision(typename element_type_trait<Tp>::element_type y)

     {

       optengine.set_precision(y);

     }

 

+

+    /**

+       perform the fitting

+     */

     Tp fit()

     {

       //      assert(p_model!=0);

@@ -1345,11 +1475,20 @@ namespace opt_utilities
   };

 

 

+

+  /**

+     virtual class representing a statistic

+     \tparam Ty the type of the model return type

+     \tparam Tx the type of the model self-var

+     \tparam Tp the type of the model param

+     \tparam Ts statistic type

+     \tparam Tstr the type of string used

+  */

   template<typename Ty,typename Tx,typename Tp,typename Ts,typename Tstr=std::string>

   class statistic

     :public func_obj<Ts,Tp>

   {

-  public:

+  private:

     fitter<Ty,Tx,Tp,Ts,Tstr>* p_fitter;

   

   private:

@@ -1361,23 +1500,40 @@ namespace opt_utilities
     }

 

   public:

+    /**

+       clone the existing object

+       \return the clone of self

+     */

     statistic<Ty,Tx,Tp,Ts,Tstr>* clone()const

     {

       return this->do_clone();

     }

     

+    /**

+       destroy the cloned object

+     */

     void destroy()

     {

       return do_destroy();

     }

+

+    /**

+       default construct

+     */

     statistic()

       :p_fitter(0)

     {}

     

+    /**

+       copy construct

+     */

     statistic(const statistic& rhs)

       :p_fitter(rhs.p_fitter)

     {}

 

+    /**

+       assignment operator

+     */

     statistic& operator=(const statistic& rhs)

     {

       if(this==&rhs)

@@ -1388,14 +1544,27 @@ namespace opt_utilities
       return *this;

     }

     

+

+    /**

+       destructure function

+     */

     virtual ~statistic()

     {}

 

+    /**

+       set the fitter

+       \param pfitter the fitter to be linked

+    */

     virtual void set_fitter(fitter<Ty,Tx,Tp,Ts,Tstr>& pfitter)

     {

       p_fitter=&pfitter;

     }

 

+

+    /**

+       get the attached fitter

+       \return the const reference of the fitter object

+     */

     virtual const fitter<Ty,Tx,Tp,Ts,Tstr>& get_fitter()const

     {

       if(p_fitter==0)

@@ -1405,6 +1574,12 @@ namespace opt_utilities
       return *p_fitter;

     }

 		

+    /**

+       evaluating the model

+       \param x the self-var

+       \param p the parameter

+       \return the evaluated model value

+     */

     Ty eval_model(const Tx& x,const Tp& p)

     {

       if(p_fitter==0)

@@ -1414,7 +1589,10 @@ namespace opt_utilities
       return p_fitter->eval_model(x,p);

     }

 

-		

+    /**

+       get the data_set object managed by the fitter object

+       \return the const reference of the data_set object

+     */

     const data_set<Ty,Tx>& get_data_set()const

     {

       if(p_fitter==0)

@@ -1426,41 +1604,71 @@ namespace opt_utilities
 

   };

 

+

+  /**

+     Used to modify the parameter, e.g., freezing, bind

+     \tparam Ty the type of the model return type

+     \tparam Tx the type of the model self-var

+     \tparam Tp the type of the model param

+     \tparam Tstr the type of string used

+  */

   template <typename Ty,typename Tx,typename Tp,typename Tstr=std::string>

   class param_modifier

   {

   private:

     model<Ty,Tx,Tp,Tstr>* p_model;

   public:

+    /**

+       constructing full parameter list from the free parameters

+     */

     Tp reform(const Tp& p)const

     {

       return do_reform(p);

     }

+

+    /**

+       constructing the free parameter from the full parameters

+     */

     Tp deform(const Tp& p)const

     {

       return do_deform(p);

     }

 

+    /**

+       return the clone of self

+       \return the clone of self

+     */

     param_modifier<Ty,Tx,Tp,Tstr>* clone()const

     {

       return do_clone();

     }

-

+    

+    /**

+       destroy the cloned object

+     */

     void destroy()

     {

       do_destroy();

     }

 

   public:

-

+    /**

+       the default construct function

+     */

     param_modifier()

       :p_model(0)

     {}

     

+    /**

+       copy construct function

+     */

     param_modifier(const param_modifier& rhs)

       :p_model(rhs.p_model)

     {}

 

+    /**

+       assignment operator

+     */

     param_modifier& operator=(const param_modifier& rhs)

     {

       if(this==&rhs)

@@ -1472,12 +1680,21 @@ namespace opt_utilities
     }

     

   public:

+    

+    /**

+       Attach the fitter object

+       \param pf the fitter to be attached

+     */

     void set_model(model<Ty,Tx,Tp,Tstr>& pf)

     {

       p_model=&pf;

       update();

     }

 

+    /**

+       get the model attached

+       \return the const reference of the model

+     */

     const model<Ty,Tx,Tp,Tstr>& get_model()const

     {

       if(p_model==0)

@@ -1488,17 +1705,27 @@ namespace opt_utilities
       return *(this->p_model);

     }

 

+    /**

+       calculate the number of free parameters

+     */

     size_t get_num_free_params()const

     {

       return do_get_num_free_params();

     }

 

+    /**

+       report the status of parameters

+       \param pname parameter name

+       \return the string used to describe the parameter

+     */

     Tstr report_param_status(const Tstr& name)const

     {

       return do_report_param_status(name);

     }

 

-

+    /**

+       destruct function

+     */

     virtual ~param_modifier(){}

   private:

     virtual Tp do_reform(const Tp& p)const=0;

@@ -1515,9 +1742,6 @@ namespace opt_utilities
     }

 

   };

-  

-

-  

 }

 

 

diff --git a/core/freeze_param.hpp b/core/freeze_param.hpp
index 31541c1..4f7cc8c 100644
--- a/core/freeze_param.hpp
+++ b/core/freeze_param.hpp
@@ -1,3 +1,7 @@
+/**
+   \file freeze_param.hpp
+*/
+
 #ifndef FREEZE_PARAM_HPP
 #define FREEZE_PARAM_HPP
 #include "fitter.hpp"
@@ -6,6 +10,13 @@
 
 namespace opt_utilities
 {
+  /**
+     freeze a set of parameter in model fitting
+     \tparam Ty the return type of a model
+     \tparam Tx the type of the self-var
+     \tparam Tp the type of the model parameter
+     \tparam Tstr the type of string used
+   */
   template <typename Ty,typename Tx,typename Tp,typename Tstr=std::string>
   class freeze_param
     :public param_modifier<Ty,Tx,Tp,Tstr>
@@ -16,11 +27,17 @@ namespace opt_utilities
     size_t num_free;
     
   public:
+    /**
+       the default construct function
+     */
     freeze_param()
     {
-      
     }
-
+    
+    /**
+       construct function
+       \param name the name of the parameter to be frozen
+     */
     freeze_param(const Tstr& name)
     {
       param_names.insert(name);
@@ -33,7 +50,10 @@ namespace opt_utilities
     }
     
     
-
+    /**
+       update the parameter information
+       should be called by the library, rather than the user
+     */
     void update()
     {
       param_num.clear();
@@ -133,6 +153,12 @@ namespace opt_utilities
     }
 
   public:
+    
+    /**
+       plus operator, used to combine a list of freeze_param objects
+       \param fp another freeze_param object
+       \return the combined freeze_param object
+     */
     freeze_param operator+(const freeze_param& fp)const
     {
       freeze_param result(*this);
@@ -145,6 +171,10 @@ namespace opt_utilities
       return result;
     }
 
+    /**
+       += operator
+       like the plus operator
+     */
     freeze_param& operator+=(const freeze_param& fp)
     {
       //param_names.insert(param_names.end(),
@@ -167,6 +197,12 @@ namespace opt_utilities
       return *this;
     }
 
+
+    /**
+       un-freeze a parameter to a list of pre-frozen parameter list
+       \param fp the parameter to be un-frozen
+       \return the reference to the operated freeze_param object
+     */
     freeze_param& operator-=(const freeze_param& fp)
     {
       //param_names.insert(param_names.end(),
@@ -191,6 +227,11 @@ namespace opt_utilities
 
   };
 
+  /**
+     help function to create a freeze_param object
+     \param name the name to be frozen
+     \return the created freeze_param object
+   */
   template <typename Ty,typename Tx,typename Tp,typename Tstr>
   freeze_param<Ty,Tx,Tp,Tstr> freeze(const Tstr& name)
   {
diff --git a/core/num_diff.hpp b/core/num_diff.hpp
index f9cf520..a6d9659 100644
--- a/core/num_diff.hpp
+++ b/core/num_diff.hpp
@@ -1,3 +1,8 @@
+/**
+   \file num_diff.hpp
+ */
+
+
 #ifndef NUMDIFF_HPP
 #define NUMDIFF_HPP
 
@@ -9,6 +14,12 @@
 
 namespace opt_utilities
 {
+
+  /**
+     differentiable function
+     \tparam rT the return type
+     \tparam the parameter type
+   */
   template <typename rT,typename pT>
   class dfunc_obj
     :public func_obj<rT,pT>
@@ -17,12 +28,22 @@ namespace opt_utilities
     virtual pT do_diff(const pT& p)=0;
     
   public:
+    /**
+       calculate the differentiation
+       \param p the self-var
+       \return the gradient at p
+     */
     pT diff(const pT& p)
     {
       return do_diff(p);
     }
   };
   
+
+  /**
+     When trying to diff an object function, when it is not differentiable,
+     this exception will be thrown.
+   */
   class underivable
     :public opt_exception
   {
@@ -32,6 +53,9 @@ namespace opt_utilities
     {}
   };
 
+  /**
+     calculate the numerical differential of a func_obj
+   */
   template <typename rT,typename pT>
     pT numdiff(func_obj<rT,pT>& f,const pT& p)
   {
@@ -68,6 +92,13 @@ namespace opt_utilities
     return result;
   }
 
+
+  /**
+     Help function to calculate the gradient of an objection function 
+     func_obj, whether it is differentiable or not. If it is differentiable, 
+     the gradient will be calculated by calling the diff member in the func_obj,
+     or a numerical calculation will be performed.
+   */
   template <typename rT,typename pT>
     pT diff(func_obj<rT,pT>& f,const pT& p)
   {
diff --git a/core/opt_exception.hpp b/core/opt_exception.hpp
index 65e4470..4413da7 100644
--- a/core/opt_exception.hpp
+++ b/core/opt_exception.hpp
@@ -1,9 +1,16 @@
+/**
+   \file opt_exception.hpp
+*/
+
 #ifndef OPT_EXCEPTION
 #define OPT_EXCEPTION
 #include <string>
 #include <exception>
 namespace opt_utilities
 {
+  /**
+     the root class of exception used in opt_utilities
+   */
   class opt_exception
     :public std::exception
   {
@@ -26,6 +33,10 @@ namespace opt_utilities
     }
   };
   
+  /**
+     When objection is not defined in optimizer, and optimizion is performing,
+     this exception will be thrown
+   */
   class target_function_undefined
     :public opt_exception
   {
@@ -35,6 +46,10 @@ namespace opt_utilities
     {}
   };
 
+  /**
+     When the opt_method is not defined before the optimization is performing,
+     this exception will be thrown.
+   */
   class opt_method_undefined
     :public opt_exception
   {
@@ -44,6 +59,10 @@ namespace opt_utilities
     {}
   };
   
+  /**
+     When fitter is not attached in a model, statistic, and other objects,
+     this exception will be thrown.
+   */
   class fitter_unset
     :public opt_exception
   {
@@ -53,6 +72,11 @@ namespace opt_utilities
     {}
   };
 
+
+  /**
+     When the model is not set before the model fitting,
+     this exception will be thrown.
+   */
   class model_undefined
     :public opt_exception
   {
@@ -62,6 +86,11 @@ namespace opt_utilities
     {}
   };
 
+
+  /**
+     When the data set is not loaded before the model fitting,
+     this exception will be thrown.
+   */
   class data_unloaded
     :public opt_exception
   {
@@ -72,6 +101,10 @@ namespace opt_utilities
   };
 
 
+  /**
+     When the statistic is not set before the model fitting,
+     this exception will be thrown.
+   */
   class statistic_undefined
     :public opt_exception
   {
@@ -81,6 +114,11 @@ namespace opt_utilities
     {}
   };
   
+
+  /**
+     If a parameter is not found by the name or other information,
+     this exception will be thrown.
+   */
   class param_not_found
     :public opt_exception
   {
@@ -90,6 +128,11 @@ namespace opt_utilities
     {}
   };
   
+
+  /**
+     If param_modifier is not defined, and the user tries to get the 
+     param_modifer, this exception will be thrown.
+   */
   class param_modifier_undefined
     :public opt_exception
   {
diff --git a/core/opt_traits.hpp b/core/opt_traits.hpp
index b8426e0..7c2638a 100644
--- a/core/opt_traits.hpp
+++ b/core/opt_traits.hpp
@@ -1,22 +1,41 @@
+/**
+   \file opt_traits.hpp
+ */
+
 #ifndef ARRAY_OPERATION
 #define ARRAY_OPERATION
 #include <cstddef>
 namespace opt_utilities
 {
-  /////////Useful function///////////////////////////////////
+  /**
+     Get the size of an array object
+     \param x the array object
+     \return the size of the array object
+   */
   template <typename T>
   inline size_t get_size(const T& x)
   {
     return x.size();
   }
   
+  /**
+     Trait class, in which the types of elements in an array are defined
+     \tparam the type of the array object
+   */
   template <typename T>
   class element_type_trait
   {
   public:
+    /**
+       Default definition of element_type
+     */
     typedef typename T::value_type element_type;
   };
 
+  
+  /**
+     The return type trait of some certain data types.
+  */
   template <typename T>
   class return_type_trait
   {
@@ -26,6 +45,14 @@ namespace opt_utilities
     typedef const T& const_reference_type;
   };
   
+
+  /**
+     Help function to get the i-th element from an array
+     \tparam T the type of the array object
+     \param x the array object
+     \param i the order of the element
+     \return the fetched element value, const reference
+   */
   template <typename T>
   inline typename 
   return_type_trait<typename element_type_trait<T>::element_type>::
@@ -33,14 +60,16 @@ namespace opt_utilities
   {
     return x[i];
   }
-  /*
-  template <typename T>
-  inline typename element_type_trait<T>::element_type& get_element(T& x,size_t i)
-  {
-    return x[i];
-  }
-  */
 
+  
+  /**
+     set ths i-th element by a given value
+     \tparam T the type of the array object
+     \tparam Tx the type of the element
+     \param x the array object
+     \param i the order of the element
+     \param v the value of the element to be set
+   */
   template<typename T,typename TX>
   inline void set_element(T& x,size_t i,
 			  const TX& v)
@@ -48,12 +77,28 @@ namespace opt_utilities
     x[i]=v;
   }
 
+
+  /**
+     resize an array object
+     \tparam T the type of the array
+     \param x the array object
+     \param s the new size
+   */
   template <typename T>
   inline void resize(T& x,size_t s)
   {
     x.resize(s);
   }
 
+
+  /**
+     Assignment operator of two array objects
+     \tparam Tl the type of left-hand array
+     \tparam Tr the type of right-hand array
+     \param lhs the left-hand array
+     \param rhs the right-hand array
+     \return the reference of the left-hand array
+   */
   template <typename Tl,typename Tr>
   inline Tl& opt_eq(Tl& lhs,const Tr& rhs)
   {
diff --git a/core/optimizer.hpp b/core/optimizer.hpp
index 7492bab..2381da0 100644
--- a/core/optimizer.hpp
+++ b/core/optimizer.hpp
@@ -17,6 +17,9 @@
 using namespace std;
 #endif
 
+/**
+   The root namespace of the opt_utilities library
+ */
 namespace opt_utilities
 {
   /////////Forward declare///////////////////////////////////