Skip to content

how to document stuff most users don't want to see

13 messages · Charles Geyer, William Dunlap, Spencer Graves +5 more

Original
Charles Geyer
# 
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?
Duncan Murdoch
#
On 10/5/2009 1:50 PM, Charles Geyer wrote:
I think writing it up in a vignette would probably be most appropriate. 
  You can link directly to a vignette from a man page (though not, 
unfortunately, vice versa).  For example, if you look at
package?grid, you'll see a list that was generated by this code:

Further information is available in the following
\link{vignettes}:
\tabular{ll}{
\code{grid} \tab Introduction to \code{grid} (\url{../doc/grid.pdf})\cr
\code{displaylist} \tab Display Lists in \code{grid} 
(\url{../doc/displaylist.pdf})\cr

...

Duncan Murdoch
William Dunlap
# 
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
Spencer Graves
# 
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:

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Patrick Burns
    

    

      
      #
    

  


  

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

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        
      

    

    

      
      

        


  

        

      Seth Falcon
    

    

      
      #
    

  


  

      
Writing good documentation is hard.  I can appreciate the desire to
find technological solutions that improve documentation.  However, the
benefit of a help system that allows for varying degrees of verbosity
is very likely to be overshadowed by the additional complexity imposed
on the help system.

Users would need to learn how to tune the help system.  Developers
would need to learn and follow the system of variable verbosity.  This
time would be better spent by developers simply improving the
documentation and by users by simply reading the improved
documentation.

My $0.02.

+ seth

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Spencer Graves
    

    

      
      #
    

  


  

      
I write *.Rd files primarily because it helps me think through what I 
want the software to do AND because the "\examples" provide any degree 
of unit testing I feel I need to create "trustworth software" (to quote 
Chambers).  The fact that I can then share the resulting package with 
others is a marvelous byproduct of this approach to software 
development, but not the primary reason I do it.  Earlier today, I read 
where Hadley had had problems with my code and had to read the help file 
carefully to understand how to fix the problem.  I immediately wrote to 
Hadley inviting more input (and to my collaborator to suggest that the 
package be placed on R-Forge to make it easier for people to improve 
documentation, etc.). 


Adding my $0.02 to Seth's. 


Spencer

        
Seth Falcon wrote:

            

      
      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Patrick Burns
    

    

      
      #
    

  


  

      
Under the system of development we
now have, I agreee with Seth's
assertion.  But if there were
people dedicated to documentation,
then I think something like what I
described could be workable.

Pat

        
Seth Falcon wrote:

            

      
      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
Patrick Burns wrote:

            

      
      
      
    

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

Duncan Murdoch

            

      
      
      
    

        

      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      William Dunlap
    

    

      
      #
    

  


  

          

      
      
      
    

        
Using a link to another help file is an established
way of doing this.  Help file writers know how to put
in links and readers know how use them. Charlie's
question was how to describe the debugging output
that few people would want to know about.  I don't
think he wanted to write a narrative vignette that
told how to use the debug output to solve problems
but he wanted to make the format of the output
available.  Why not have help(myFunction) say
   debug: a logical scalar saying whether to enable [debugging
      output] or not
just as help(grep) says
   pattern: character string containing a [regular expression]
       (or character string for fixed = TRUE) to be matched
or help(title) says
    quite a bit of mathematical notation is available such as
    sub- and superscripts, greek letters, fractions, etc:
    see [plotmath]   
?  (The [] indicates a link to another Rd file that gives more
detail about the matter.)

Bill Dunlap
Spotfire, TIBCO Software
wdunlap tibco.com

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

            

      
      
      
    

  
  


  


      

    

    

      
      

        
      

    

    
1 day later

    

      
      

        


  

        

      Charles Geyer
    

    

      
      #
    

  


  

      
On Mon, Oct 05, 2009 at 02:03:51PM -0400, Duncan Murdoch wrote:

            

      
      
      
    

        
So I decided to follow your advice mcmc_0.7-3.tar.gz just uploaded to CRAN
has such a vignette and such links in the appropriate Rd files.

Thanks