Documenting classes and methods: was [Rd] Re: R-devel Digest, Vol 3, Issue 23

[Kurt Hornik]

>>>>> John Chambers writes:

> Gordon Smyth wrote:
>> 
>> 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. 

> The "structure" of the skeletons (the \alias lines especially) are
> intended to be used by the help system.  You're not meant to "use" these
> directly, much of the time.  It's the case that the tools to work with
> the .Rd structure haven't caught up yet, but please don't modify the
> skeleton's structure arbitrarily.

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

> Good point, but related to the behavior of "?".

Correct.

> It's related to a number of other issues about multiple packages
> referring to the same generic function.  Not likely to change for
> 1.7.1, but likely to be different in several ways in 1.8

Actually, there are several issues.

If two packages had a 'foo-methods' alias entry, we can still find them
(and in fact, the code in help() does so).  However, for multiple help
topic matches, we typically only display the first one, rather than
offering a selection menu, and I really think we should change this.

Re using 'foo-methods' as an alias, I am not sure whether this is
necessary in the long run.  To find out which methods are available, we
can use showMethod().  We should eventually [see below] be able to do
something like

  method ? f(x="character", y = "numeric")

to access the documentation object for the given signature, and there is
no guarantee that an f-methods Rd object really documents all methods
for the generic f in the package.  So I think eventually we should get
rid of the default foo-methods alias, and just dump the ones
corresponding to available methods.

>> 
>> 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}.

> Seems ok to have separate discussion of arguments, but don't "abandon"
> the rest of the material in the skeleton (see below).

> Heavy use of extra arguments in the methods is a little bit worrisome.
> There is an efficiency penalty, though not likely serious in sizable
> computations.  More basic (this is just my personal view), I like to
> think of the function as having a single conceptual definition--what
> it does and (by and large) what arguments it takes to describe what it
> should do.  Then the methods are the implementation.  The function
> description is likely what users, begining users particularly, want to
> see.  More advanced users and programmers may also be concerned with
> the implementation.

> So, most of the time, one would like the function to define the
> arguments, and the methods to work from these.

Right, but perhaps there should still be \usage markup for S4 methods in
case people want to document methods with 'surprising arguments'.  One
idea would be to have

	\S4method{generic}{signaturelist}(arglist)

which could on output render to e.g.

	## Method for signature 'signaturelist':
	generic(arglist)

> In some examples of extra arguments (the S3 print() methods, for
> instance), these are style-setting parameters, or perhaps control
> parameters for numeric computations.  It might be clearer in such
> cases to say that "..." is always passed to a (class-dependant)
> parameter-setting function.  Documenting that function is then a
> separate step.

> Again, this is just by way of what may help users to understand the
> functions and help designers to write functions cleanly; not
> suggesting you should be forced to take this route.

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

> Don't do that.  It's not what you like that counts, it's what works
> with the ? function, and your change will wipe out the ability of the
> help functions to identify correctly which method is being documented.

> For 1.8 (unfortunately, unlikely to be ironed out for 1.7.1), users
> should be able to get documentation on the method, say, for function
> f(x,y) corresponding to signature(x = "character", y = "numeric") by the
> expression
>   method ? f(x="character", y = "numeric")
> (or something along these lines).

> In any case, the \alias lines are crucial to going from any way of
> requesting method documentation to the correct documentation.

Definitely.

Best
-k