[Roxygen-devel] S4 documentation

[Colin A. Smith]

I'm developing a new, relatively complex, R package right now. It's been a while since I've done so and had more recently been doing a lot of C++ programming with Doxygen. I've found manually maintaining Rd files to be a real pain, and was really happy to find Roxygen.

For the most part, packages that I've written (and am currently writing) have complex classes that store and process a large amount of data. There are usually many generics with only a single method each. The xcms package has several such classes:

http://www.bioconductor.org/packages/release/bioc/html/xcms.html

For that package, some of of the methods were so simple that the method/generic documentation was kept in the class itself, which would add a type of documentation to the list below. More complex methods got their own page.

I have some code written for class documentation which pulls method descriptions in during the roxygenize() call. I haven't pushed that out to Github yet because I'm waiting on how my other pull request goes. :-)

Cheers.

-Colin

> Hi all,
> 
> I've been spending some time thinking about how to document S4
> methods, and I've included my current thoughts so far.  I'd really
> appreciate your feedback, so we can get roxygen2 working well with S4.
> 
> # Methods
> 
> Two types of generics:
> 
> * Large number of simple methods such as in the Matrix package. All methods
>   have the same arguments with the same meaning and no `...`. Often dispatch
>   on multiple parameters, leading to a combinatorial explosion of methods.
>   This also includes methods like `length` which many classes implement, but
>   are typically intuitive and need little explanation.
> 
>   Methods are only listed in the generic so you know what is available.
> 
>   Method look up goes directly to the generic.
> 
> * Small number of complex methods, where each method needs individual
>   documentation. This includes methods like `print`, where different classes
>   have different arguments. Similarly, model methods like `predict` and
>   `anova` typically need documentation for individual methods because that's
>   where it is most appropriate to describe the statistical operation.
> 
>   Methods are listed in the generic along with a brief description and a
>   pointer to more information. They have their own topics and method lookup
>   goes to individual methods.
> 
>   This style of method seems to be somewhat more prevalent in S3.
> 
> The user should be able to switch between these two types of documentation:
> 
> * if method only has description, defaults to including in generic
> * if method has anything more than a description, gets own file.
> 
> Question: should all methods get their own file? If yes, then what
> should the name/alias for the topic be because the main alias should
> be in the generic.
> 
> # Generics
> 
> Generics use `\Sexpr{}` to dynamically list method descriptions from
> other locations at render time. Uses `findMethods()` to find all
> methods corresponding to the generic, then determines the topic name
> for each method, then determines the Rd file name, then extracts the
> description for each Rd file. (Will need to exclude methods already
> documented in the generic). All methods documented in a given topic
> are grouped together.
> 
> Methods should be listed in a `Methods` section, sorted by signature.
> 
> # Classes
> 
> Similarly, class uses `\Sexpr{}` to pull in minimal method description
> for all class methods. Also need `\Sexpr{}` macro to list all
> subclasses of the class.  See `class?diagonalMatrix` for a good
> example.  Class should have slots, which by default is a list of slot
> names and their known prototypes. Optionally overridden by the user
> with `@slot` tag.
> 
> Hadley