Search code examples
rdevtoolsroxygen2

Roxygen2 cannot process files begining with underscore?

I have a collection of small functions that I would like to add to an R package. I list all the functions in a single file, preceeded for each by Roxygen2 indications for building the help file (an example below). It all works well. However, I noted that when I rename that file to begin with an underscore (so that it appears first in my list of files), I get the following error message:

Updating mypackage documentation
Loading mypackage
Writing NAMESPACE
Writing NAMESPACE
Warning message:
In setup_ns_exports(path, export_all, export_imports) :
  Objects listed as exports, but not present in namespace: a, b

Here is the content of the only file in the R subfolder:

#' @name a
#' @title the a() function does etc.
#' @description etc.
#' @param x a dataframe containing etc.;
#' @param v a vector containing etc..
#' @return a dataframe of the etc.
#' @export a
a <- function(x, v) { return("somevalue") }

#' @name b
#' @title the b() function does etc.  
#' @description etc.
#' @param x a dataframe containing etc.;
#' @param v a vector containing etc..
#' @return a dataframe of the etc.
#' @export b
b <- function(x, v) { return("some other value") }

When I remove the underscore, and re-run devtools::document() twice, the error message disapear. I put back the underscore and the error is back. When there is no Roxygen2 tags, there are no error and the functions work nice.

Is this a normal behavior? Is there a way around this error or should I just give up the idea of using the underscore?

Solution

  • It's not (just) roxygen2, it's an R thing.

    From Writing R Extensions, subsection 1.1.5 Package subdirectories:

    The R subdirectory contains R code files, only. The code files to be installed must start with an ASCII (lower or upper case) letter or digit and have one of the extensions .R, .S, .q, .r, or .s.

    Similarly,

    The man subdirectory should contain (only) documentation files for the objects in the package in R documentation (Rd) format. The documentation filenames must start with an ASCII (lower or upper case) letter or digit and have the extension .Rd (the default) or .rd.

    This generally isn't an issue using roxygen2: while it does name the .Rd files based on the function names, and R doesn't allow function names (typically) that start with underscore. From the R Language Definition subsection 10.3.2 Identifiers:

    Identifiers consist of a sequence of letters, digits, the period (‘.’) and the underscore. They must not start with a digit or an underscore, or with a period followed by a digit.

    While it is possible to define a function with an identifier that begins with an underscore, it requires wrapping the function name in backticks for definition and any time it is used (since it is not a "valid identifier").