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

[Charles Geyer]

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