Hey guys,<br><br>These are the two basic design approaches when it comes to S4 programming:<br><br>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. <br>
<br>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.<br>
<br><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><br>
<br>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. <br>
<br>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{}.<br>
<br>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.<br>
<br>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. <br>
<br>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. <br>
<br>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.<br>
<br>One last thing: documentation for classes can get pretty long. Is there a way to @include extra files? Steve Lianoglou had this idea.<br><br>Michael<br>