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

From: Hervé Pagès <hpages_at_fhcrc.org>
Date: Wed, 24 Oct 2012 13:12:04 -0700


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:

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,

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

R-devel_at_r-project.org mailing list
Received on Wed 24 Oct 2012 - 20:14:21 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Wed 24 Oct 2012 - 20:40:51 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive