[Roxygen-devel] S4 documentation

[Michael Lawrence]

To add on to this a little bit, there needs to be convenient support for
generating NAMESPACE imports.

If a class is included in a method signature, or is passed in "contains" to
setClass(), and it is not defined within the package, Roxygen should search
the dependent packages for a class of the same name and generate an
importClassesFrom() directive. User should be able to override, just in
case it picks the wrong package.

When a method is defined for a generic not defined in the package, search
the dependencies and importFrom() it.

On Sat, Nov 12, 2011 at 5:55 AM, Michael Lawrence <michafla at gene.com> wrote:

> 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/20111119/4c5cccd5/attachment.htm>