[Roxygen-devel] S4 documentation

[Michael Lawrence]

On Mon, Nov 14, 2011 at 7:08 AM, Hadley Wickham <hadley at rice.edu> wrote:

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


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


> > 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)
>
>
There may be a use-case for @including Roxygen comments, but I think my
use-case would benefit more from pure Rd that would just be concatenated
into the resulting Rd file. These would be things like extra \section{}s.
Maybe make that more explicit with a @section that refers to a file?



> Hadley
>
> --
> Assistant Professor / Dobelman Family Junior Chair
> Department of Statistics / Rice University
> http://had.co.nz/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20111114/5f0ca7e6/attachment.htm>