[Rd] how to document stuff most users don't want to see
spencer.graves at prodsyse.com
Mon Oct 5 21:01:32 CEST 2009
There are many arguments in many functions that are rarely used. I
prefer to see it all documented in the help pages. If they are not
documented in the help pages (and sometimes even if they are), a user
who wants them can invent other ways to get similar information with
much greater effort, and do so for years only to eventually find a much
easier way buried in the documentation. Example: I was frustrated for
years that "nls" would refuse to produce output if it did not converge.
I often used "optim" instead of "nls" for that reason. However, the
list returned by "optim" does not have the nice methods that one can use
with an "nls" object. Eventually, I found the "warnOnly" option
documented under "nls.control", which has made "nls" easier for me to use.
William Dunlap wrote:
> There are several help files in the R sources that
> describe concepts and not particular R objects.
> E.g., help(Methods), help(Syntax), and help(regex).
> They don't have a docType entry and their alias
> entries do not refer to functions. Perhaps your
> debugging documentation could go into a similar
> *.Rd file.
> Does check balk at such help files in a package? Should it?
> Should there be a special docType for such help files?
> Bill Dunlap
> Spotfire, TIBCO Software
> wdunlap tibco.com
>> -----Original Message-----
>> From: r-devel-bounces at r-project.org
>> [mailto:r-devel-bounces at r-project.org] On Behalf Of Charles Geyer
>> Sent: Monday, October 05, 2009 10:51 AM
>> To: r-devel at r-project.org
>> Subject: [Rd] how to document stuff most users don't want to see
>> The functions metrop and temper in the mcmc package have a
>> debug = FALSE
>> argument that when TRUE adds a lot of debugging information
>> to the returned
>> list. This is absolutely necessary to test the functions, because one
>> generally knows nothing about the simulated distribution
>> except what what
>> one learns from MCMC samples. Hence you must expose all
>> details of the
>> simulation to have any hope of checking that it is doing what
>> it is supposed
>> to do. However, this information is of interested mostly
>> (perhaps solely)
>> to developers. So I didn't document it in the Rd files for
>> these functions.
>> But it has ocurred to me that people might be interested in
>> how these functions
>> are validated, and I would like to document the debug output
>> somewhere, but I
>> don't want to clutter up the documentation that ordinary
>> users see. That
>> suggests a separate help page for debugging. Looking at
>> "Writing R Extensions"
>> it doesn't seem like there is a type of Rd file for this
>> purpose. I suppose
>> it could be added in (fairly long) sections titled "Debug
>> Output" in metrop.Rd
>> and temper.Rd or it could be put in a package help page
>> (although that's not
>> what that kind of page is really for). Any other
>> possibilities to consider?
>> Charles Geyer
>> Professor, School of Statistics
>> University of Minnesota
>> charlie at stat.umn.edu
>> R-devel at r-project.org mailing list
> R-devel at r-project.org mailing list
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
More information about the R-devel