[Rd] how to document stuff most users don't want to see
wdunlap at tibco.com
Mon Oct 5 20:32:17 CEST 2009
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
Does check balk at such help files in a package? Should it?
Should there be a special docType for such help files?
Spotfire, TIBCO Software
> -----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
More information about the R-devel