[Roxygen-devel] S4 documentation

[Hadley Wickham]

> <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>

Thanks for the explanation!

> 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.

A similarly, classes should point to all parent and child classes.

> 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.

I think the first step is to develop an object representation of R
documentation, backed by Rd files.  Once we have that working (which
already would be very useful for roxygen2), it would be possible to
explore different backing systems: xml, mallard, sqlite etc.

> 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.

Yes, user specifiable sub-classes would be cool.  How this interacts
with the compilation process that turns roxygen comments in to
documentation objects might be complex, however.

>  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{}.

Ah, yes, that's a cool idea.  In principle, the Rd file could just be
\Sexpr{generateRd("topicname")}.  But in practice, you'd probably want
some stuff statically generated like the name and aliases.

> 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.

Ooh, I like that idea.

> 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.

I like that idea too.

> 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.

You mean hiding in the documentation sense, right?  Sort of privacy by
convention?

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

That's another interesting idea.  We currently have @template, which
is a superset of @include, but it might be worthwhile differentiating
them semantically.  Where would you imagine such include files living?
 Would they be R files or plain text to be interpreted as roxygen
comments?  (We decided on R files for templates so that existing
syntax highlighting code would work)

Hadley

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