[Rd] Shouldn't the \usage section tell the truth?

[Hervé Pagès]

Hi,

The signature of mget() changed between R-2.15.1 and recent R-devel.

In R-2.15.1:

   > args(mget)
   function (x, envir, mode = "any", ifnotfound = list(function(x) 
stop(paste0("value for '",
       x, "' not found"), call. = FALSE)), inherits = FALSE)
   NULL

In R-devel:

   > args(mget)
   function (x, envir, mode = "any", ifnotfound = list(function(x) 
stop(gettextf("value for %s not found",
       sQuote(x)), call. = FALSE, domain = NA)), inherits = FALSE)
   NULL

What has changed exactly is the default value for the 'ifnotfound'
argument. This change generates an 'R CMD check' warning for the
BiocGenerics package where the \usage section is still using
the old default:

   * checking for code/documentation mismatches ... WARNING
   Codoc mismatches from documentation object 'get':
   mget
     Code: function(x, envir, mode = "any", ifnotfound = list(function(x)
                    stop(gettextf("value for %s not found", sQuote(x)),
                    call. = FALSE, domain = NA)), inherits = FALSE)
     Docs: function(x, envir, mode = "any", ifnotfound = list(function(x)
                    stop(paste0("value for '", x, "' not found"), call. =
                    FALSE)), inherits = FALSE)
     Mismatches in argument default values:
       Name: 'ifnotfound'
       Code: list(function(x) stop(gettextf("value for %s not found", 
sQuote(x)),
             call. = FALSE, domain = NA))
       Docs: list(function(x) stop(paste0("value for '", x, "' not found"),
             call. = FALSE))

It's good to have the warning, and the fix is easy.

Now surprisingly, in R-devel, the \usage section for mget() doesn't
show the new default value (it used to in previous versions of R):

   mget(x, envir, mode = "any", ifnotfound, inherits = FALSE)

As you can see, it doesn't show a default value at all! And it
seems that 'R CMD check' is fine with that.

So my question is: is this the intended behavior for 'R CMD check'?
I hope not.

My view on argument default values is that they are fully part of the
API so they should appear in the \usage section. I can see that the
default value for 'ifnotfound' is not very exciting and showing it
in the \usage section is not that helpful (and can fairly be considered
distracting). But isn't this a situation where the default value
should rather be set to NULL or NA? Or, alternatively, no default
value is specified in the argument list and 'if (missing(ifnotfound))'
is used internally? Note that what is shown in \usage for mget() is
suggesting that this last solution was retained, which is misleading.
Then, whatever solution is used (NULL, NA, or no default value at
all), the documentation should probably explain how the argument
will be handled in case it's missing (unless this is obvious).

Anyway, what solution should be retained for mget() is not important.
My point is that the \usage section should tell the truth, and, if
not, 'R CMD check' should issue a warning.

Many times we've seen argument default values for Bioconductor functions 
not reported in the \usage section. Each time it was
*not* intended (typically the maintainer would add the argument
default value in the function definition and forget to update the
\usage section). And each time, when someone brings this to the
attention of the maintainer (sometimes weeks or months later),
everybody was surprised that 'R CMD check' didn't report the problem.

Hopefully that can be fixed.

Thanks in advance,
H.

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fhcrc.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319