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-boun...@r-project.org > [mailto:r-devel-boun...@r-project.org] On Behalf Of Charles Geyer > Sent: Monday, October 05, 2009 10:51 AM > To: r-devel@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 > char...@stat.umn.edu > > ______________________________________________ > R-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel > ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
