[R-package] add deprecation warnings about some uses of '...' (#4522)

Co-authored-by: Nikita Titov <nekit94-12@hotmail.com>

R-package/R/lgb.Dataset.R

@@ -831,7 +831,7 @@ lgb.Dataset.construct <- function(dataset) {
 #' @title Dimensions of an \code{lgb.Dataset}
 #' @description Returns a vector of numbers of rows and of columns in an \code{lgb.Dataset}.
 #' @param x Object of class \code{lgb.Dataset}
-#' @param ... other parameters
+#' @param ... other parameters (ignored)
 #'
 #' @return a vector of numbers of rows and of columns
 #'
@@ -853,6 +853,16 @@ lgb.Dataset.construct <- function(dataset) {
 #' @export
 dim.lgb.Dataset <- function(x, ...) {
 
+  additional_args <- list(...)
+  if (length(additional_args) > 0L) {
+    warning(paste0(
+      "dim.lgb.Dataset: Found the following passed through '...': "
+      , paste(names(additional_args), collapse = ", ")
+      , ". These are ignored. In future releases of lightgbm, this warning will become an error. "
+      , "See ?dim.lgb.Dataset for documentation on how to call this function."
+    ))
+  }
+
   # Check if dataset is not a dataset
   if (!lgb.is.Dataset(x = x)) {
     stop("dim.lgb.Dataset: input data should be an lgb.Dataset object")
@@ -978,7 +988,7 @@ slice.lgb.Dataset <- function(dataset, idxset, ...) {
 #' @description Get one attribute of a \code{lgb.Dataset}
 #' @param dataset Object of class \code{lgb.Dataset}
 #' @param name the name of the information field to get (see details)
-#' @param ... other parameters
+#' @param ... other parameters (ignored)
 #' @return info data
 #'
 #' @details
@@ -1017,6 +1027,16 @@ getinfo <- function(dataset, ...) {
 #' @export
 getinfo.lgb.Dataset <- function(dataset, name, ...) {
 
+  additional_args <- list(...)
+  if (length(additional_args) > 0L) {
+    warning(paste0(
+      "getinfo.lgb.Dataset: Found the following passed through '...': "
+      , paste(names(additional_args), collapse = ", ")
+      , ". These are ignored. In future releases of lightgbm, this warning will become an error. "
+      , "See ?getinfo.lgb.Dataset for documentation on how to call this function."
+    ))
+  }
+
   # Check if dataset is not a dataset
   if (!lgb.is.Dataset(x = dataset)) {
     stop("getinfo.lgb.Dataset: input dataset should be an lgb.Dataset object")
@@ -1032,7 +1052,7 @@ getinfo.lgb.Dataset <- function(dataset, name, ...) {
 #' @param dataset Object of class \code{lgb.Dataset}
 #' @param name the name of the field to get
 #' @param info the specific field of information to set
-#' @param ... other parameters
+#' @param ... other parameters (ignored)
 #' @return the dataset you passed in
 #'
 #' @details
@@ -1071,6 +1091,16 @@ setinfo <- function(dataset, ...) {
 #' @export
 setinfo.lgb.Dataset <- function(dataset, name, info, ...) {
 
+  additional_args <- list(...)
+  if (length(additional_args) > 0L) {
+    warning(paste0(
+      "setinfo.lgb.Dataset: Found the following passed through '...': "
+      , paste(names(additional_args), collapse = ", ")
+      , ". These are ignored. In future releases of lightgbm, this warning will become an error. "
+      , "See ?setinfo.lgb.Dataset for documentation on how to call this function."
+    ))
+  }
+
   if (!lgb.is.Dataset(x = dataset)) {
     stop("setinfo.lgb.Dataset: input dataset should be an lgb.Dataset object")
   }

R-package/R/lgb.cv.R

@@ -52,6 +52,7 @@ CVBooster <- R6::R6Class(
 #'                             not the number of threads (most CPU using hyper-threading to generate 2 threads
 #'                             per CPU core).}
 #'            }
+#'            NOTE: As of v3.3.0, use of \code{...} is deprecated. Add parameters to \code{params} directly.
 #' @inheritSection lgb_shared_params Early Stopping
 #' @return a trained model \code{lgb.CVBooster}.
 #'
@@ -108,13 +109,23 @@ lgb.cv <- function(params = list()
   }
 
   # Setup temporary variables
-  params <- append(params, list(...))
+  additional_params <- list(...)
+  params <- append(params, additional_params)
   params$verbose <- verbose
   params <- lgb.check.obj(params = params, obj = obj)
   params <- lgb.check.eval(params = params, eval = eval)
   fobj <- NULL
   eval_functions <- list(NULL)
 
+  if (length(additional_params) > 0L) {
+    warning(paste0(
+      "lgb.cv: Found the following passed through '...': "
+      , paste(names(additional_params), collapse = ", ")
+      , ". These will be used, but in future releases of lightgbm, this warning will become an error. "
+      , "Add these to 'params' instead. See ?lgb.cv for documentation on how to call this function."
+    ))
+  }
+
   # set some parameters, resolving the way they were passed in with other parameters
   # in `params`.
   # this ensures that the model stored with Booster$save() correctly represents

R-package/R/lgb.train.R

@@ -24,6 +24,7 @@
 #'                             not the number of threads (most CPU using hyper-threading to generate 2 threads
 #'                             per CPU core).}
 #'            }
+#'            NOTE: As of v3.3.0, use of \code{...} is deprecated. Add parameters to \code{params} directly.
 #' @inheritSection lgb_shared_params Early Stopping
 #' @return a trained booster model \code{lgb.Booster}.
 #'
@@ -91,6 +92,15 @@ lgb.train <- function(params = list(),
   fobj <- NULL
   eval_functions <- list(NULL)
 
+  if (length(additional_params) > 0L) {
+    warning(paste0(
+      "lgb.train: Found the following passed through '...': "
+      , paste(names(additional_params), collapse = ", ")
+      , ". These will be used, but in future releases of lightgbm, this warning will become an error. "
+      , "Add these to 'params' instead. See ?lgb.train for documentation on how to call this function."
+    ))
+  }
+
   # set some parameters, resolving the way they were passed in with other parameters
   # in `params`.
   # this ensures that the model stored with Booster$save() correctly represents

R-package/man/dim.Rd

@@ -9,7 +9,7 @@
 \arguments{
 \item{x}{Object of class \code{lgb.Dataset}}
 
-\item{...}{other parameters}
+\item{...}{other parameters (ignored)}
 }
 \value{
 a vector of numbers of rows and of columns

R-package/man/getinfo.Rd

@@ -12,7 +12,7 @@ getinfo(dataset, ...)
 \arguments{
 \item{dataset}{Object of class \code{lgb.Dataset}}
 
-\item{...}{other parameters}
+\item{...}{other parameters (ignored)}
 
 \item{name}{the name of the information field to get (see details)}
 }

R-package/man/lgb.cv.Rd

@@ -128,7 +128,8 @@ into a predictor model which frees up memory and the original datasets}
                  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
                  per CPU core).}
-}}
+}
+NOTE: As of v3.3.0, use of \code{...} is deprecated. Add parameters to \code{params} directly.}
 }
 \value{
 a trained model \code{lgb.CVBooster}.

R-package/man/lgb.train.Rd

@@ -110,7 +110,8 @@ the "Parameters" section of the documentation} for more information. A few key p
                  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
                  per CPU core).}
-}}
+}
+NOTE: As of v3.3.0, use of \code{...} is deprecated. Add parameters to \code{params} directly.}
 }
 \value{
 a trained booster model \code{lgb.Booster}.

R-package/man/setinfo.Rd

@@ -12,7 +12,7 @@ setinfo(dataset, ...)
 \arguments{
 \item{dataset}{Object of class \code{lgb.Dataset}}
 
-\item{...}{other parameters}
+\item{...}{other parameters (ignored)}
 
 \item{name}{the name of the field to get}