There are many arguments in many functions that are rarely used. I
prefer to see it all documented in the help pages. If they are not
documented in the help pages (and sometimes even if they are), a user
who wants them can invent other ways to get similar information with
much greater effort, and do so for years only to eventually find a much
easier way buried in the documentation. Example: I was frustrated for
years that "nls" would refuse to produce output if it did not converge.
I often used "optim" instead of "nls" for that reason. However, the
list returned by "optim" does not have the nice methods that one can use
with an "nls" object. Eventually, I found the "warnOnly" option
documented under "nls.control", which has made "nls" easier for me to use.
Spencer Graves
William Dunlap wrote:
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
--
Spencer Graves, PE, PhD
President and Chief Operating Officer
Structure Inspection and Monitoring, Inc.
751 Emerson Ct.
San José, CA 95126
ph: 408-655-4567
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
