[Roxygen-devel] Documenting S4 methods

[Hadley Wickham]

Hi all,

After a survey of packages that use S4 and talking to a few people who
use S4 a lot, here are my thoughts on how method documentation would
work.

Methods need to be documented in three places:

* individually, for complex methods
* in the class (briefly)
* in the generic (briefly)

This distinction arises in part because there seem to be two main classes of
generic functions:

* Generics with many simple methods, like `length` and many of the methods in
  the `Matrix package`. There is little use of `...`. They often dispatch on
  multiple arguments. Typically, the individual methods don't need much
  documentation (i.e. it's usually obvious what `length` does)

* Generics with few complex methods, like `predict`, `anova`. These
  methods often use ..., to pass in additional information needed for a
  specific method. The individual methods need substantial documentation to
  (e.g.) explain the details of statistical operation.

So some methods need to document their parameters and provide
examples, others need a sentence or two, and quite a few no
documentation at all (like methods for `show`).

To deal with this variation, I propose that all documentation be
method based, and roxygen then deals with assembling summaries into
the class and generic documentation. Class and generics would always
list all applicable methods, and include title and description if
present. If the method has a title, it will also get its own
documentation page, and the class/generic list would link to the full
information.

Here are a few examples:

* Does not have own topic, but presence noted on class/generic page:

  setMethod("show", "MyClass", ...)

* Does not have own topic, but brief description included on class/generic
  page:

  #' @description A statistical summary of \code{\link{MyClass}} which
  #'   computes a five number summary for element in the list.
  setMethod("summary", "MyClass", ...)

* Has own own topic, and brief description + link included on class/generic
  page:

  #' Complex method for my object
  #'
  #' This complex method implements the Cramer-Rao lower bound estimator
  #' for MyObject objects.  The statistical methodology is described in
  #' ...
  #'
  #' @examples
  #' # Here are some examples using it in practice...
  setMethod("complexMethod", "MyClass", ...)

What do you think?

Thanks!

Hadley

-- 
RStudio / Rice University
http://had.co.nz/