[docs][R-package] update docs on C++ interface (#4257)

* [R-package] update docs on C++ interface

* Update R-package/src/lightgbm_R.h
Co-authored-by: Nikita Titov <nekit94-08@mail.ru>

* Update R-package/src/lightgbm_R.h
Co-authored-by: Nikita Titov <nekit94-08@mail.ru>

* add missing start_iteration doc
Co-authored-by: Nikita Titov <nekit94-08@mail.ru>

R-package/src/lightgbm_R.h

@@ -15,22 +15,19 @@
 
 /*!
 * \brief get string message of the last error
-*  all functions in this file will return 0 on success
-*  and -1 when an error occurred
-* \return err_msg error information
-* \return error information
+* \return err_msg string with error information
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_GetLastError_R();
 
 // --- start Dataset interface
 
 /*!
-* \brief load data set from file like the command_line LightGBM does
+* \brief load Dataset from file like the command_line LightGBM does
 * \param filename the name of the file
 * \param parameters additional parameters
-* \param reference used to align bin mapper with other dataset, nullptr means not used
-* \param out created dataset
-* \return 0 when succeed, -1 when failure happens
+* \param reference used to align bin mapper with other Dataset, nullptr means not used
+* \param out created Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromFile_R(
   SEXP filename,
@@ -40,7 +37,7 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromFile_R(
 );
 
 /*!
-* \brief create a dataset from CSC format
+* \brief create a Dataset from Compressed Sparse Column (CSC) format
 * \param indptr pointer to row headers
 * \param indices findex
 * \param data fvalue
@@ -48,9 +45,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromFile_R(
 * \param nelem number of nonzero elements in the matrix
 * \param num_row number of rows
 * \param parameters additional parameters
-* \param reference used to align bin mapper with other dataset, nullptr means not used
-* \param out created dataset
-* \return 0 when succeed, -1 when failure happens
+* \param reference used to align bin mapper with other Dataset, nullptr means not used
+* \param out created Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromCSC_R(
   SEXP indptr,
@@ -65,14 +62,14 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromCSC_R(
 );
 
 /*!
-* \brief create dataset from dense matrix
-* \param data matric data
+* \brief create Dataset from dense matrix
+* \param data matrix data
 * \param num_row number of rows
 * \param num_col number columns
 * \param parameters additional parameters
-* \param reference used to align bin mapper with other dataset, nullptr means not used
-* \param out created dataset
-* \return 0 when succeed, -1 when failure happens
+* \param reference used to align bin mapper with other Dataset, nullptr means not used
+* \param out created Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromMat_R(
   SEXP data,
@@ -84,13 +81,13 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetCreateFromMat_R(
 );
 
 /*!
-* \brief Create subset of a data
-* \param handle handle of full dataset
+* \brief Create subset of a Dataset
+* \param handle handle of full Dataset
 * \param used_row_indices Indices used in subset
 * \param len_used_row_indices length of Indices used in subset
 * \param parameters additional parameters
-* \param out created dataset
-* \return 0 when succeed, -1 when failure happens
+* \param out created Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetSubset_R(
   LGBM_SE handle,
@@ -104,7 +101,7 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetSubset_R(
 * \brief save feature names to Dataset
 * \param handle handle
 * \param feature_names feature names
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetFeatureNames_R(
   LGBM_SE handle,
@@ -125,10 +122,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFeatureNames_R(
 );
 
 /*!
-* \brief save dataset to binary file
-* \param handle an instance of dataset
+* \brief save Dataset to binary file
+* \param handle an instance of Dataset
 * \param filename file name
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSaveBinary_R(
   LGBM_SE handle,
@@ -136,9 +133,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSaveBinary_R(
 );
 
 /*!
-* \brief free dataset
-* \param handle an instance of dataset
-* \return 0 when succeed, -1 when failure happens
+* \brief free Dataset
+* \param handle an instance of Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetFree_R(
   LGBM_SE handle
@@ -148,11 +145,11 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetFree_R(
 * \brief set vector to a content in info
 *        Note: group and group_id only work for C_API_DTYPE_INT32
 *              label and weight only work for C_API_DTYPE_FLOAT32
-* \param handle an instance of dataset
+* \param handle an instance of Dataset
 * \param field_name field name, can be label, weight, group, group_id
 * \param field_data pointer to vector
 * \param num_element number of element in field_data
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetField_R(
   LGBM_SE handle,
@@ -162,11 +159,11 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetSetField_R(
 );
 
 /*!
-* \brief get size of info vector from dataset
-* \param handle an instance of dataset
+* \brief get size of info vector from Dataset
+* \param handle an instance of Dataset
 * \param field_name field name
-* \param out size of info vector from dataset
-* \return 0 when succeed, -1 when failure happens
+* \param out size of info vector from Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFieldSize_R(
   LGBM_SE handle,
@@ -175,11 +172,11 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetFieldSize_R(
 );
 
 /*!
-* \brief get info vector from dataset
-* \param handle an instance of dataset
+* \brief get info vector from Dataset
+* \param handle an instance of Dataset
 * \param field_name field name
 * \param field_data pointer to vector
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetField_R(
   LGBM_SE handle,
@@ -188,10 +185,11 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetField_R(
 );
 
 /*!
- * \brief Raise errors for attempts to update dataset parameters
- * \param old_params Current dataset parameters
- * \param new_params New dataset parameters
- * \return 0 when succeed, -1 when failure happens
+ * \brief Raise errors for attempts to update Dataset parameters.
+ *        Some parameters cannot be updated after construction.
+ * \param old_params Current Dataset parameters
+ * \param new_params New Dataset parameters
+ * \return R NULL value
  */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetUpdateParamChecking_R(
   SEXP old_params,
@@ -200,9 +198,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetUpdateParamChecking_R(
 
 /*!
 * \brief get number of data.
-* \param handle the handle to the dataset
+* \param handle the handle to the Dataset
 * \param out The address to hold number of data
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumData_R(
   LGBM_SE handle,
@@ -211,9 +209,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumData_R(
 
 /*!
 * \brief get number of features
-* \param handle the handle to the dataset
+* \param handle the handle to the Dataset
 * \param out The output of number of features
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumFeature_R(
   LGBM_SE handle,
@@ -224,10 +222,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_DatasetGetNumFeature_R(
 
 /*!
 * \brief create a new boosting learner
-* \param train_data training data set
+* \param train_data training Dataset
 * \param parameters format: 'key1=value1 key2=value2'
 * \param out handle of created Booster
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreate_R(
   LGBM_SE train_data,
@@ -236,19 +234,19 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreate_R(
 );
 
 /*!
-* \brief free obj in handle
+* \brief free Booster
 * \param handle handle to be freed
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterFree_R(
   LGBM_SE handle
 );
 
 /*!
-* \brief load an existing boosting from model file
+* \brief load an existing Booster from model file
 * \param filename filename of model
 * \param out handle of created Booster
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreateFromModelfile_R(
   SEXP filename,
@@ -256,10 +254,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCreateFromModelfile_R(
 );
 
 /*!
-* \brief load an existing boosting from model_str
+* \brief load an existing Booster from a string
 * \param model_str string containing the model
 * \param out handle of created Booster
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterLoadModelFromString_R(
   SEXP model_str,
@@ -267,10 +265,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterLoadModelFromString_R(
 );
 
 /*!
-* \brief Merge model in two boosters to first handle
-* \param handle handle, will merge other handle to this
-* \param other_handle
-* \return 0 when succeed, -1 when failure happens
+* \brief Merge model in two Boosters to first handle
+* \param handle handle primary Booster handle, will merge other handle to this
+* \param other_handle secondary Booster handle
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterMerge_R(
   LGBM_SE handle,
@@ -278,10 +276,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterMerge_R(
 );
 
 /*!
-* \brief Add new validation to booster
-* \param handle handle
-* \param valid_data validation data set
-* \return 0 when succeed, -1 when failure happens
+* \brief Add new validation to Booster
+* \param handle Booster handle
+* \param valid_data validation Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterAddValidData_R(
   LGBM_SE handle,
@@ -289,10 +287,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterAddValidData_R(
 );
 
 /*!
-* \brief Reset training data for booster
-* \param handle handle
-* \param train_data training data set
-* \return 0 when succeed, -1 when failure happens
+* \brief Reset training data for Booster
+* \param handle Booster handle
+* \param train_data training Dataset
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetTrainingData_R(
   LGBM_SE handle,
@@ -300,10 +298,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetTrainingData_R(
 );
 
 /*!
-* \brief Reset config for current booster
-* \param handle handle
+* \brief Reset config for current Booster
+* \param handle Booster handle
 * \param parameters format: 'key1=value1 key2=value2'
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetParameter_R(
   LGBM_SE handle,
@@ -312,9 +310,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterResetParameter_R(
 
 /*!
 * \brief Get number of classes
-* \param handle handle
+* \param handle Booster handle
 * \param out number of classes
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumClasses_R(
   LGBM_SE handle,
@@ -323,21 +321,21 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumClasses_R(
 
 /*!
 * \brief update the model in one round
-* \param handle handle
-* \return 0 when succeed, -1 when failure happens
+* \param handle Booster handle
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIter_R(
   LGBM_SE handle
 );
 
 /*!
-* \brief update the model, by directly specify gradient and second order gradient,
+* \brief update the model, by directly specifying gradient and second order gradient,
 *       this can be used to support customized loss function
-* \param handle handle
+* \param handle Booster handle
 * \param grad gradient statistics
 * \param hess second order gradient statistics
 * \param len length of grad/hess
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIterCustom_R(
   LGBM_SE handle,
@@ -348,8 +346,8 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterUpdateOneIterCustom_R(
 
 /*!
 * \brief Rollback one iteration
-* \param handle handle
-* \return 0 when succeed, -1 when failure happens
+* \param handle Booster handle
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterRollbackOneIter_R(
   LGBM_SE handle
@@ -357,8 +355,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterRollbackOneIter_R(
 
 /*!
 * \brief Get iteration of current boosting rounds
+* \param handle Booster handle
 * \param out iteration of boosting rounds
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetCurrentIteration_R(
   LGBM_SE handle,
@@ -367,9 +366,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetCurrentIteration_R(
 
 /*!
 * \brief Get model upper bound value.
-* \param handle Handle of booster
+* \param handle Handle of Booster
 * \param[out] out_results Result pointing to max value
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetUpperBoundValue_R(
     LGBM_SE handle,
@@ -378,9 +377,9 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetUpperBoundValue_R(
 
 /*!
 * \brief Get model lower bound value.
-* \param handle Handle of booster
+* \param handle Handle of Booster
 * \param[out] out_results Result pointing to min value
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetLowerBoundValue_R(
     LGBM_SE handle,
@@ -401,10 +400,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEvalNames_R(
 
 /*!
 * \brief get evaluation for training data and validation data
-* \param handle handle
+* \param handle Booster handle
 * \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
-* \param out_result float array contains result
-* \return 0 when succeed, -1 when failure happens
+* \param out_result float array containing result
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEval_R(
   LGBM_SE handle,
@@ -414,10 +413,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetEval_R(
 
 /*!
 * \brief Get number of prediction for training data and validation data
-* \param handle handle
+* \param handle Booster handle
 * \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
 * \param out size of predict
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumPredict_R(
   LGBM_SE handle,
@@ -428,10 +427,10 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetNumPredict_R(
 /*!
 * \brief Get prediction for training data and validation data.
 *        This can be used to support customized eval function
-* \param handle handle
+* \param handle Booster handle
 * \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
 * \param out_result, used to store predict result, should pre-allocate memory
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetPredict_R(
   LGBM_SE handle,
@@ -441,14 +440,19 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterGetPredict_R(
 
 /*!
 * \brief make prediction for file
-* \param handle handle
+* \param handle Booster handle
 * \param data_filename filename of data file
 * \param data_has_header data file has header or not
-* \param is_rawscore
-* \param is_leafidx
+* \param is_rawscore 1 to get raw predictions, before transformations like
+*                    converting to probabilities, 0 otherwise
+* \param is_leafidx 1 to get record of which leaf in each tree
+*                   observations fell into, 0 otherwise
+* \param is_predcontrib 1 to get feature contributions, 0 otherwise
+* \param start_iteration Start index of the iteration to predict
 * \param num_iteration number of iteration for prediction, <= 0 means no limit
-* \return 0 when succeed, -1 when failure happens
-* \return 0 when succeed, -1 when failure happens
+* \param parameter additional parameters
+* \param result_filename filename of file to write predictions to
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForFile_R(
   LGBM_SE handle,
@@ -465,13 +469,17 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForFile_R(
 
 /*!
 * \brief Get number of prediction
-* \param handle handle
-* \param num_row
-* \param is_rawscore
-* \param is_leafidx
+* \param handle Booster handle
+* \param num_row number of rows in input
+* \param is_rawscore 1 to get raw predictions, before transformations like
+*                    converting to probabilities, 0 otherwise
+* \param is_leafidx 1 to get record of which leaf in each tree
+*                   observations fell into, 0 otherwise
+* \param is_predcontrib 1 to get feature contributions, 0 otherwise
+* \param start_iteration Start index of the iteration to predict
 * \param num_iteration number of iteration for prediction, <= 0 means no limit
 * \param out_len length of prediction
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCalcNumPredict_R(
   LGBM_SE handle,
@@ -485,22 +493,27 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterCalcNumPredict_R(
 );
 
 /*!
-* \brief make prediction for a new data set
+* \brief make prediction for a new Dataset
 *        Note:  should pre-allocate memory for out_result,
 *               for normal and raw score: its length is equal to num_class * num_data
 *               for leaf index, its length is equal to num_class * num_data * num_iteration
-* \param handle handle
+* \param handle Booster handle
 * \param indptr pointer to row headers
 * \param indices findex
 * \param data fvalue
 * \param num_indptr number of cols in the matrix + 1
 * \param nelem number of non-zero elements in the matrix
 * \param num_row number of rows
-* \param is_rawscore
-* \param is_leafidx
+* \param is_rawscore 1 to get raw predictions, before transformations like
+*                    converting to probabilities, 0 otherwise
+* \param is_leafidx 1 to get record of which leaf in each tree
+*                   observations fell into, 0 otherwise
+* \param is_predcontrib 1 to get feature contributions, 0 otherwise
+* \param start_iteration Start index of the iteration to predict
 * \param num_iteration number of iteration for prediction, <= 0 means no limit
-* \param out prediction result
-* \return 0 when succeed, -1 when failure happens
+* \param parameter additional parameters
+* \param out_result prediction result
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSC_R(
   LGBM_SE handle,
@@ -520,19 +533,24 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForCSC_R(
 );
 
 /*!
-* \brief make prediction for a new data set
+* \brief make prediction for a new Dataset
 *        Note:  should pre-allocate memory for out_result,
 *               for normal and raw score: its length is equal to num_class * num_data
 *               for leaf index, its length is equal to num_class * num_data * num_iteration
-* \param handle handle
+* \param handle Booster handle
 * \param data pointer to the data space
 * \param num_row number of rows
 * \param num_col number columns
-* \param is_rawscore
-* \param is_leafidx
+* \param is_rawscore 1 to get raw predictions, before transformations like
+*                    converting to probabilities, 0 otherwise
+* \param is_leafidx 1 to get record of which leaf in each tree
+*                   observations fell into, 0 otherwise
+* \param is_predcontrib 1 to get feature contributions, 0 otherwise
+* \param start_iteration Start index of the iteration to predict
 * \param num_iteration number of iteration for prediction, <= 0 means no limit
-* \param out prediction result
-* \return 0 when succeed, -1 when failure happens
+* \param parameter additional parameters
+* \param out_result prediction result
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMat_R(
   LGBM_SE handle,
@@ -550,10 +568,11 @@ LIGHTGBM_C_EXPORT SEXP LGBM_BoosterPredictForMat_R(
 
 /*!
 * \brief save model into file
-* \param handle handle
+* \param handle Booster handle
 * \param num_iteration, <= 0 means save all
+* \param feature_importance_type type of feature importance, 0: split, 1: gain
 * \param filename file name
-* \return 0 when succeed, -1 when failure happens
+* \return R NULL value
 */
 LIGHTGBM_C_EXPORT SEXP LGBM_BoosterSaveModel_R(
   LGBM_SE handle,