docs: clarify R CMD check NOTE for .. prefix

man/special-symbols.Rd

@@ -27,7 +27,8 @@
         \item \code{.N} is an integer, length 1, containing the number of rows in the group. This may be useful when the column names are not known in advance and for convenience generally. When grouping by \code{i}, \code{.N} is the number of rows in \code{x} matched to, for each row of \code{i}, regardless of whether \code{nomatch} is \code{NA} or \code{NULL}. It is renamed to \code{N} (no dot) in the result (otherwise a column called \code{".N"} could conflict with the \code{.N} variable, see FAQ 4.6 for more details and example), unless it is explicitly named; e.g., \code{DT[,list(total=.N),by=a]}.
         \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{.NGRP} is an integer, length 1, containing the number of groups.
+        \item \code{..} prefix: Looks up a variable in the calling scope. In packages, using the \code{..} prefix may trigger an \code{R CMD check} NOTE because the variable is treated as an undefined global variable. This can be avoided by registering the variable with \code{utils::globalVariables()}, or, where appropriate, by using alternatives such as \code{with=FALSE} or \code{env=}.
     }
 
     \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

@@ -127,6 +127,24 @@ aggr = function (x) {
 }
 ```
 
+The `..` prefix (for example, `DT[, ..cols]`) looks up a variable in the calling scope. In R packages, using the `..` prefix may trigger an `R CMD check` NOTE because `..cols` is treated as an undefined global variable.
+```r
+cols = c("x", "y")
+DT[, ..cols]   # may trigger an R CMD check NOTE
+```
+
+To avoid the NOTE, either register the variable with
+```r
+utils::globalVariables("..cols")
+```
+
+or, where appropriate, use an alternative interface such as
+```r
+DT[, cols, with = FALSE]
+DT[, .SD, .SDcols = cols]
+DT[, is.other, env = list(is.other = is.other)]
+```
+
 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:
 
 ```r

vignettes/datatable-programming.Rmd

@@ -197,6 +197,9 @@ DT[filter_col %in% filter_val,
      by_col =  "Species"
   )]
 ```
+#### Note for package developers: The `..` prefix
+
+Using the `..` prefix (for example, `DT[, ..cols]`) may trigger an `R CMD check` NOTE because `..cols` is treated as an undefined global variable. To avoid the NOTE, either register the variable with `utils::globalVariables("..cols")` or, where appropriate, use alternatives such as `with=FALSE` or the `env=` interface instead of the `..` prefix.
 
 ### Substitute functions