[R-package] clarify parameter documentation (fixes #4193) (#4202)

* [R-package] clarify parameter documentation

* fixes to braces

* linting

Author: jameslamb

R-package/R/lgb.Dataset.R

@@ -730,11 +730,22 @@ Dataset <- R6::R6Class(
 #' @description Construct \code{lgb.Dataset} object from dense matrix, sparse matrix
 #'              or local file (that was created previously by saving an \code{lgb.Dataset}).
 #' @param data a \code{matrix} object, a \code{dgCMatrix} object or a character representing a filename
-#' @param params a list of parameters
-#' @param reference reference dataset
+#' @param params a list of parameters. See
+#'               \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html#dataset-parameters}{
+#'               The "Dataset Parameters" section of the documentation} for a list of parameters
+#'               and valid values.
+#' @param reference reference dataset. When LightGBM creates a Dataset, it does some preprocessing like binning
+#'                  continuous features into histograms. If you want to apply the same bin boundaries from an existing
+#'                  dataset to new \code{data}, pass that existing Dataset to this argument.
 #' @param colnames names of columns
-#' @param categorical_feature categorical features
-#' @param free_raw_data TRUE for need to free raw data after construct
+#' @param categorical_feature categorical features. This can either be a character vector of feature
+#'                            names or an integer vector with the indices of the features (e.g.
+#'                            \code{c(1L, 10L)} to say "the first and tenth columns").
+#' @param free_raw_data LightGBM constructs its data format, called a "Dataset", from tabular data.
+#'                      By default, that Dataset object on the R side does not keep a copy of the raw data.
+#'                      This reduces LightGBM's memory consumption, but it means that the Dataset object
+#'                      cannot be changed after it has been constructed. If you'd prefer to be able to
+#'                      change the Dataset object after construction, set \code{free_raw_data = FALSE}.
 #' @param info a list of information of the \code{lgb.Dataset} object
 #' @param ... other information to pass to \code{info} or parameters pass to \code{params}
 #'

R-package/R/lgb.train.R

@@ -5,19 +5,20 @@
 #' @param valids a list of \code{lgb.Dataset} objects, used for validation
 #' @param record Boolean, TRUE will record iteration message to \code{booster$record_evals}
 #' @param colnames feature names, if not null, will use this to overwrite the names in dataset
-#' @param categorical_feature list of str or int
-#'                            type int represents index,
-#'                            type str represents feature names
+#' @param categorical_feature categorical features. This can either be a character vector of feature
+#'                            names or an integer vector with the indices of the features (e.g.
+#'                            \code{c(1L, 10L)} to say "the first and tenth columns").
 #' @param callbacks List of callback functions that are applied at each iteration.
 #' @param reset_data Boolean, setting it to TRUE (not the default value) will transform the
 #'                   booster model into a predictor model which frees up memory and the
 #'                   original datasets
-#' @param ... other parameters, see Parameters.rst for more information. A few key parameters:
+#' @param ... other parameters, see \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html}{
+#'            the "Parameters" section of the documentation} for more information. A few key parameters:
 #'            \itemize{
 #'                \item{\code{boosting}: Boosting type. \code{"gbdt"}, \code{"rf"}, \code{"dart"} or \code{"goss"}.}
 #'                \item{\code{num_leaves}: Maximum number of leaves in one tree.}
 #'                \item{\code{max_depth}: Limit the max depth for tree model. This is used to deal with
-#'                                 overfit when #data is small. Tree still grow by leaf-wise.}
+#'                                 overfitting. Tree still grow by leaf-wise.}
 #'                \item{\code{num_threads}: Number of threads for LightGBM. For the best speed, set this to
 #'                             the number of real CPU cores(\code{parallel::detectCores(logical = FALSE)}),
 #'                             not the number of threads (most CPU using hyper-threading to generate 2 threads

R-package/R/lightgbm.R

@@ -5,10 +5,11 @@
 #' @param data a \code{lgb.Dataset} object, used for training. Some functions, such as \code{\link{lgb.cv}},
 #'             may allow you to pass other types of data like \code{matrix} and then separately supply
 #'             \code{label} as a keyword argument.
-#' @param early_stopping_rounds int. Activates early stopping. Requires at least one validation data
-#'                              and one metric. If there's more than one, will check all of them
-#'                              except the training data. Returns the model with (best_iter + early_stopping_rounds).
-#'                              If early stopping occurs, the model will have 'best_iter' field.
+#' @param early_stopping_rounds int. Activates early stopping. When this parameter is non-null,
+#'                              training will stop if the evaluation of any metric on any validation set
+#'                              fails to improve for \code{early_stopping_rounds} consecutive boosting rounds.
+#'                              If training stops early, the returned model will have attribute \code{best_iter}
+#'                              set to the iteration number of the best iteration.
 #' @param eval evaluation function(s). This can be a character vector, function, or list with a mixture of
 #'             strings and functions.
 #'
@@ -48,7 +49,8 @@
 #' @param obj objective function, can be character or custom objective function. Examples include
 #'            \code{regression}, \code{regression_l1}, \code{huber},
 #'            \code{binary}, \code{lambdarank}, \code{multiclass}, \code{multiclass}
-#' @param params List of parameters
+#' @param params a list of parameters. See \href{https://lightgbm.readthedocs.io/en/latest/Parameters.html}{
+#'               the "Parameters" section of the documentation} for a list of parameters and valid values.
 #' @param verbose verbosity for output, if <= 0, also will disable the print of evaluation during training
 #' @section Early Stopping:
 #'

R-package/R/saveRDS.lgb.Booster.R

@@ -2,7 +2,7 @@
 #' @title saveRDS for \code{lgb.Booster} models
 #' @description Attempts to save a model using RDS. Has an additional parameter (\code{raw})
 #'              which decides whether to save the raw model or not.
-#' @param object R object to serialize.
+#' @param object \code{lgb.Booster} object to serialize.
 #' @param file a connection or the name of the file where the R object is saved to or read from.
 #' @param ascii a logical. If TRUE or NA, an ASCII representation is written; otherwise (default),
 #'              a binary one is used. See the comments in the help for save.