[Rd] how to document stuff most users don't want to see

[Patrick Burns]

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
>>>
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>     
>>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>   
> 
>