how to document stuff most users don't want to see
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