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

[spencerg]

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
>
>   


-- 
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