I think the problem is more subtle
than Spencer implies. It is good
to have as much documentation as
possible. However, if a help file
is long and complex, then people
get intimidated and don't read it
at all.
It would be nice to have a feature
so that help files can be displayed
with different levels of detail. A
sophisticated version of this scheme
might even assume different levels of
knowledge of the user so that the least
detailed level might be longer (but
easier) than a more detailed level.
Patrick Burns
patr...@burns-stat.com
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of "The R Inferno" and "A Guide for the Unwilling S User")
spencerg wrote:
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
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
