In some cases it would be nice to have a lot of examples explaining the
different uses of different parameters instead of the more usual.

I like the way in which log4j allows one to parameterise at runtime the
verboseness of different parts of a runtime.  So hypothetically (and
assuming a lot!) one could have a default amount of help info and a
different default amount of examples... so when printed the default info
wouldn't be too overwhelming - but it would be possible to ask for more
info.

Sean


On Tue, Oct 6, 2009 at 8:53 AM, Patrick Burns <pburns@pburns.seanet.com>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.
>
>
>
> Patrick Burns
> patrick@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@r-project.org [mailto:
>>>> r-devel-bounces@r-project.org] On Behalf Of Charles Geyer
>>>> Sent: Monday, October 05, 2009 10:51 AM
>>>> To: r-devel@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@stat.umn.edu
>>>>
>>>> ______________________________________________
>>>> R-devel@r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>
>>>>
>>>>
>>>
>>> ______________________________________________
>>> R-devel@r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>
>>>
>>>
>>
>>
>>
> ______________________________________________
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

	[[alternative HTML version deleted]]

