[Rd] how to document stuff most users don't want to see

[William Dunlap]

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
> https://stat.ethz.ch/mailman/listinfo/r-devel
>