[Roxygen-devel] S4 documentation

[Hadley Wickham]

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



-- 
Assistant Professor / Dobelman Family Junior Chair
Department of Statistics / Rice University
http://had.co.nz/