docs: clarify R CMD check NOTE for .. prefix

man/special-symbols.Rd

@@ -28,6 +28,7 @@
         \item \code{.I} is an integer vector equal to \code{seq_len(nrow(x))}. While grouping, it holds for each item in the group, its row location in \code{x}. This is useful to subset in \code{j}; e.g. \code{DT[, .I[which.max(somecol)], by=grp]}. If used in \code{by} it corresponds to applying a function rowwise. 
         \item \code{.GRP} is an integer, length 1, containing a simple group counter. 1 for the 1st group, 2 for the 2nd, etc.
         \item \code{.NGRP} is an integer, length 1, containing the number of groups. 
+        \item \code{..} prefix: Signals to look for a variable in the calling scope.
     }
 
     \code{.EACHI} is defined as \code{NULL} but its value is not used. Its usage is \code{by=.EACHI} (or \code{keyby=.EACHI}) which invokes grouping-by-each-row-of-i; see \code{\link{data.table}}'s \code{by} argument for more details.

vignettes/datatable-importing.Rmd

@@ -125,6 +125,23 @@ aggr = function (x) {
   )
   x[, .N, by = "grp"]
 }
+
+The `..` prefix (for example, `DT[, ..cols]`) looks up a variable in the calling scope. In R packages, this triggers an `R CMD check` NOTE. To avoid this, set the variable to `NULL` inside the function:
+
+```r
+gen = function(dt, cols) {
+  ..cols = NULL
+  dt[, ..cols]
+}
+```
+
+Alternatively, you can avoid the prefix entirely by using `with = FALSE`, `.SDcols`, or the env argument:
+
+```r
+# Alternatives that avoid the .. prefix
+dt[, cols, with = FALSE]
+dt[, .SD, .SDcols = cols]
+dt[, cols, env = list(cols = cols)]
 ```
 
 The case for `data.table`'s special symbols (e.g. `.SD` and `.N`) and assignment operator (`:=`) is slightly different (see `?.N` for more, including a complete listing of such symbols). You should import whichever of these values you use from `data.table`'s namespace to protect against any issues arising from the unlikely scenario that we change the exported value of these in the future, e.g. if you want to use `.N`, `.I`, and `:=`, a minimal `NAMESPACE` would have: