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

[Duncan Murdoch]

Patrick Burns wrote:
> 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.
>   

We do have that.  Vignettes can be linked to help, and they can be 
arbitrarily complex, including examples with graphs, etc.

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