[Rd] Re: R-devel Digest, Vol 3, Issue 23

[Gordon Smyth]

I am another person who has had trouble documenting S4 classes and 
(particularly) methods. The methods package itself is pretty cool by the 
way, but it is a pity that there are as yet no guidelines on S4 in the 
"Writing R Extensions" document.

I have actually put together a guide on S4 documentation myself for the use 
of my own lab which is at http://bioinf.wehi.edu.au/limma/Rdocs.html. I 
don't pretend that the guide is perfect - I can already see problems with 
it - but it has proved adequate so far for our own use (writing the limma 
package) and has gained some more general acceptance from the Bioconductor 
community.

I found it hard to use the skeleton documentation provided by 
promptMethods. Suppose for example that I wish to document a method for 
generic function 'foo' with argument list (x,y,...) for x of class 'bar1' 
and y of class 'bar2':

1. The skeleton .Rd file contains \alias{foo-methods}. If two or more more 
packages document methods for 'foo', they'll all have the same alias entry, 
and the help that a user will get by typing ?"foo-methods" will depend on 
which package happens to have been loaded most recently.

2. There seems to be no allowance for documenting extra named arguments for 
this method which are not specified in the generic. There is no usage 
entry, no argument list, and no process for R CMD check to check the 
argument list against the definition of the method. In S3 one can write 
\usage{\method{generic}{class}} and it would be nice to have an extension 
of this facility for S4 methods. I have been abandoning the skeleton 
structure produced by promptMethods and have been using \section{Usage} and 
\section{Arguments}.

3. The aliases for methods are pretty verbose and make the html contents 
page for the package look rather cluttered. I have been deleting the 
\alias{foo-methods} alias and been replacing \alias{foo,bar1,bar2-method} 
with \alias{foo.bar1.bar2}. I know that using a syntactically valid name 
for the alias has the potential problem that a function could actually 
exist with that name, but I just like to use something shorter.

4. There don't seem to be any guidelines for documenting a method with the 
generic, if the generic happens to be defined in the same package, or with 
the object class, if the generic dispatches on only one argument. I know 
that you have thought about this, and in the document 
http://developer.r-project.org/moreClassMethodIssues.html you refer to the 
'addTo' argument for 'promptMethods'. The 'addTo' argument however has not 
yet been implemented in R.

It would be nice to have a method for finding dynamically all available 
documentation for methods for a given generic function. I wrote a little 
prototype function called 'helpMethods' which simply extracts the list of 
available methods and prompts the user for which help topic they'd like to 
read. For this to work though, developers need to use a consistent alias 
system for documenting methods. I haven't seen any package yet which is 
using the aliases suggested by promptMethods.

Do you think there is any value in my S4 documentation guide? Are there 
errors or mis-understandings in it which should be corrected before it is 
adopted as a guideline by Bioconductor?

Are there major changes planned for the documentation system for S4 methods 
and classes in R in the near future? Is it worth our while spending time 
working out guidelines now or should we wait a bit until the situation 
stabilizes?

Best wishes
Gordon

>Date: Fri, 23 May 2003 15:37:50 -0400
>From: John Chambers <jmc at research.bell-labs.com>
>Subject: Re: [Rd] Documenting S4 classes; debugging them
>To: Duncan Murdoch <dmurdoch at pair.com>
>Cc: r-devel at stat.math.ethz.ch
>
>Duncan Murdoch wrote:
> >
> > 1.  I'm putting together my first package that uses S4 classes and
> > objects.  I'd like to document them, but I'm not sure what the
> > documentation should look like, and package.skeleton doesn't produce
> > any at all for the classes or methods.
>
>Hmm, sounds as if it should.
>
>Meanwhile, promptClass and promptMethods generate skeleton
>documentation.
>
> >
> > Are there any good examples to follow?
>
>The bioconductor packages (e.g, Biobase) have some examples.

...

>John
>
> >
> > Duncan Murdoch
> >
> > ______________________________________________
> > R-devel at stat.math.ethz.ch mailing list
> > https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
>
>--
>John M. Chambers                  jmc at bell-labs.com
>Bell Labs, Lucent Technologies    office: (908)582-2681
>700 Mountain Avenue, Room 2C-282  fax:    (908)582-3340
>Murray Hill, NJ  07974            web: http://www.cs.bell-labs.com/~jmc

---------------------------------------------------------------------------------------
Dr Gordon K Smyth, Senior Research Scientist, Bioinformatics,
Walter and Eliza Hall Institute of Medical Research,
1G Royal Parade, Parkville, Vic 3050, Australia
Tel: (03) 9345 2326, Fax (03) 9347 0852,
Email: smyth at wehi.edu.au, www: http://www.statsci.org