[Rd] how to document stuff most users don't want to see
murdoch at stats.uwo.ca
Wed Oct 7 12:25:30 CEST 2009
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.
> Patrick Burns
> patrick at burns-stat.com
> +44 (0)20 8525 0696
> (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
>>>> list. This is absolutely necessary to test the functions, because one
>>>> generally knows nothing about the simulated distribution except 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
>>>> to do. However, this information is of interested mostly (perhaps
>>>> to developers. So I didn't document it in the Rd files for these
>>>> But it has ocurred to me that people might be interested in how these
>>>> 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.
>>>> suggests a separate help page for debugging. Looking at "Writing R
>>>> it doesn't seem like there is a type of Rd file for this purpose. I
>>>> it could be added in (fairly long) sections titled "Debug Output" in
>>>> 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
>>>> Charles Geyer
>>>> Professor, School of Statistics
>>>> University of Minnesota
>>>> charlie at stat.umn.edu
>>>> R-devel at r-project.org mailing list
>>> R-devel at r-project.org mailing list
> R-devel at r-project.org mailing list
More information about the R-devel