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 <pbu...@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 > patr...@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-boun...@r-project.org [mailto: >>>> r-devel-boun...@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 >>>> char...@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]] ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
