R devel - Oct 2009 - 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

On 10/5/2009 1:50 PM, Charles Geyer wrote:
> 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?
I think writing it up in a vignette would probably be most appropriate. 
  You can link directly to a vignette from a man page (though not, 
unfortunately, vice versa).  For example, if you look at
package?grid, you'll see a list that was generated by this code:

Further information is available in the following
\link{vignettes}:
\tabular{ll}{
\code{grid} \tab Introduction to \code{grid} (\url{../doc/grid.pdf})\cr
\code{displaylist} \tab Display Lists in \code{grid} 
(\url{../doc/displaylist.pdf})\cr

...

Duncan Murdoch

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
>