how to document stuff most users don't want to see

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
patrick at 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-bounces at r-project.org 
[mailto:r-devel-bounces at r-project.org] On Behalf Of Charles Geyer
Sent: Monday, October 05, 2009 10:51 AM
To: r-devel at 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
charlie at stat.umn.edu