[Roxygen-devel] S4 documentation

[Michael Lawrence]

Hey guys,

These are the two basic design approaches when it comes to S4 programming:

1) Generic-centric: This corresponds to Hadley's first classification and
is the "functional OOP" style, where there is a function that is "extended"
with methods.

2) Class-centric: This is the conventional class-based OOP approach, where
generics are sort of abused into providing methods "belonging" to classes.
Generally, these only have a single argument in their signature. I think
this is more along the lines of Colin's use-case. This also matches up with
R5 classes.

<sidenote>Although in many cases one could create such class-based methods
with simple functions, if someone wants to override one in a subclass, they
will need to create a method (which would create an implicit generic,
defaulting to the original function). Usually though, that implicit generic
is undesirable, because it does not a well-defined signature. In
particular, it might not have "..." in its signature. This is often
desirable, because methods can add formal arguments to that "...", separate
from their signature, and this needs to be handled. Anyway, the generic
should probably be defined in the first package; otherwise, we might end up
with multiple generics across packages that would need to have consistent
signatures.</sidenote>

Every project is usually some mix of the above styles. A reasonable object
model for this would have classes, generics and methods, with methods
pointing to their generic and all of the classes in their signature (these
generics and classes could be defined in other packages). The
implementation could simply use the methods package for keeping track of
this.

It is clear that the user wants multiple views of the documentation. As
Hadley brought up, it is desirable to have dynamic class-centric,
generic-centric and method-centric views. The Rd is one type of view. How
to store the data?  Adding the documentation in a formal structure to each
class, generic and method object would be awesome. Not sure how to
implement it (maybe extend them? RoxygenStandardGeneric, etc?).  Anyway,
that would allow all sorts of complex views. It would also allow packages
that employ meta-programming, i.e., writing a function that defines one
type of class (like setPropertySet and setEnum in objectProperties),
because that function could auto-generate and transform the documentation,
as well. It would also allow language bindings to derive/R-ify
documentation from external libraries. R5 already has the "doc string", but
we would want a formal object of some sort. To support the R help() view,
we would need files in the Rd that would be largely generated with \Sexpr{}.

If the above is too far fetched, then we could serialize that documentation
to a database, probably Rd in the 'man' directory, with liberal use of
\Sexpr{}, as Hadley suggests. Every object would get its own file.

As far as the views of generics and classes, Hadley's plan is a good start.
In addition, we would want more cross-references between classes, generics
and methods. The methods are the edges in a bipartite graph of classes and
generics. In other words, the generic document would have a \seealso{} or
something that links to the classes included in one of the method
signatures for the generic, as a summary. Similarly, the class document
would have a summary section linking to all generics that have it in a
method signature.

For consistency, every method should have a view, and it should be richer
than simply documenting the method like a function. It could, for example,
have a \seealso{} to all methods on that generic with signatures that match
at least one class in its signature. Here "match" would mean not always the
same class, but a subclass or superclass, as well.

For classes, displaying the slots should be optional. Often, that would
just be an implementation detail. I would say always hide a slot unless
explicitly asked to make it public. Up for discussion. The class document
would want to group its methods by generic and collapse them somehow. If
there is a single method matching the class, briefly list its documentation
(which somehow includes the generic description). This satisfies the
class-centric case. If there are multiple methods, list the generic
description, and available method signatures, with links.

One last thing: documentation for classes can get pretty long. Is there a
way to @include extra files? Steve Lianoglou had this idea.

Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20111112/38abd506/attachment.htm>