add detailed comment about gbmcore

booster/xgboost_gbmbase.h

@@ -21,13 +21,28 @@ namespace xgboost{
          * \brief a base model class, 
          *        that assembles the ensembles of booster together and provide single routines to do prediction buffer and update
          *        this class can be used as base code to create booster variants 
-         *
+         *         *
          *  relation to xgboost.h:
          *    (1) xgboost.h provides a interface to a single booster(e.g. a single regression tree )
          *        while GBMBaseModel builds upon IBooster to build a class that 
          *        ensembls the boosters together;
          *    (2) GBMBaseModel provides prediction buffering scheme to speedup training;
          *    (3) Summary: GBMBaseModel is a standard wrapper for boosting ensembles;
+         *
+         *  Usage of this class, the number index gives calling dependencies:
+         *    (1) model.SetParam to set the parameters
+         *    (2) model.LoadModel to load old models or model.InitModel to create a new model
+         *    (3) model.InitTrainer before calling model.Predict and model.DoBoost
+         *    (4) model.Predict to get predictions given a instance
+         *    (4) model.DoBoost to update the ensembles, add new booster to the model
+         *    (4) model.SaveModel to save learned results 
+         *
+         *  Bufferring: each instance comes with a buffer_index in Predict. 
+         *              when param.num_pbuffer != 0, a unique buffer index can be 
+         *              assigned to each instance to buffer previous results of boosters,
+         *              this helps to speedup training, so consider assign buffer_index 
+         *              for each training instances, if buffer_index = -1, the code
+         *              recalculate things from scratch and will still works correctly
          */
         class GBMBaseModel{
         public:
@@ -214,7 +229,8 @@ namespace xgboost{
 
                 // load buffered results if any
                 if( param.do_reboost == 0 && buffer_index >= 0 ){
-                    utils::Assert( buffer_index < param.num_pbuffer, "buffer index exceed num_pbuffer" );
+                    utils::Assert( buffer_index < param.num_pbuffer, 
+                                   "buffer index exceed num_pbuffer" );
                     istart = this->pred_counter[ buffer_index ];
                     psum   = this->pred_buffer [ buffer_index ];
                 }
@@ -278,4 +294,3 @@ namespace xgboost{
     };
 };
 #endif
-

utils/xgboost_stream.h

@@ -9,7 +9,9 @@
  */
 namespace xgboost{
     namespace utils{
-        /*! \brief interface of stream I/O, used to serialize model */
+        /*! 
+         * \brief interface of stream I/O, used to serialize model 
+         */
         class IStream{
         public:
             /*! 

utils/xgboost_utils.h

@@ -51,7 +51,8 @@ namespace xgboost{
         inline void Warning( const char *msg ){
             fprintf( stderr, "warning:%s\n",msg );
         }
-        /*! \brief replace fopen, report error when the file open fails */        
+
+        /*! \brief replace fopen, report error when the file open fails */
         inline FILE *FopenCheck( const char *fname , const char *flag ){
             FILE *fp = fopen64( fname , flag );
             if( fp == NULL ){