<br><br><div class="gmail_quote">On Mon, Nov 14, 2011 at 7:08 AM, Hadley Wickham <span dir="ltr"><<a href="mailto:hadley@rice.edu">hadley@rice.edu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">> <sidenote>Although in many cases one could create such class-based methods<br>
> with simple functions, if someone wants to override one in a subclass, they<br>
> will need to create a method (which would create an implicit generic,<br>
> defaulting to the original function). Usually though, that implicit generic<br>
> is undesirable, because it does not a well-defined signature. In particular,<br>
> it might not have "..." in its signature. This is often desirable, because<br>
> methods can add formal arguments to that "...", separate from their<br>
> signature, and this needs to be handled. Anyway, the generic should probably<br>
> be defined in the first package; otherwise, we might end up with multiple<br>
> generics across packages that would need to have consistent<br>
> signatures.</sidenote><br>
<br>
</div>Thanks for the explanation!<br>
<div class="im"><br>
> Every project is usually some mix of the above styles. A reasonable object<br>
> model for this would have classes, generics and methods, with methods<br>
> pointing to their generic and all of the classes in their signature (these<br>
> generics and classes could be defined in other packages). The implementation<br>
> could simply use the methods package for keeping track of this.<br>
<br>
</div>A similarly, classes should point to all parent and child classes.<br>
<div class="im"><br>
> It is clear that the user wants multiple views of the documentation. As<br>
> Hadley brought up, it is desirable to have dynamic class-centric,<br>
> generic-centric and method-centric views. The Rd is one type of view. How to<br>
> store the data? Adding the documentation in a formal structure to each<br>
> class, generic and method object would be awesome.<br>
<br>
</div>I think the first step is to develop an object representation of R<br>
documentation, backed by Rd files. Once we have that working (which<br>
already would be very useful for roxygen2), it would be possible to<br>
explore different backing systems: xml, mallard, sqlite etc.<br>
<div class="im"><br></div></blockquote><div><br>Sounds good.<br> <br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div class="im">
> Not sure how to implement<br>
> it (maybe extend them? RoxygenStandardGeneric, etc?). Anyway, that would<br>
> allow all sorts of complex views. It would also allow packages that employ<br>
> meta-programming, i.e., writing a function that defines one type of class<br>
> (like setPropertySet and setEnum in objectProperties), because that function<br>
> could auto-generate and transform the documentation, as well.<br>
<br>
</div>Yes, user specifiable sub-classes would be cool. How this interacts<br>
with the compilation process that turns roxygen comments in to<br>
documentation objects might be complex, however.<br>
<div class="im"><br>
> It would also<br>
> allow language bindings to derive/R-ify documentation from external<br>
> libraries. R5 already has the "doc string", but we would want a formal<br>
> object of some sort. To support the R help() view, we would need files in<br>
> the Rd that would be largely generated with \Sexpr{}.<br>
<br>
</div>Ah, yes, that's a cool idea. In principle, the Rd file could just be<br>
\Sexpr{generateRd("topicname")}. But in practice, you'd probably want<br>
some stuff statically generated like the name and aliases.<br>
<div class="im"><br>
> As far as the views of generics and classes, Hadley's plan is a good start.<br>
> In addition, we would want more cross-references between classes, generics<br>
> and methods. The methods are the edges in a bipartite graph of classes and<br>
> generics. In other words, the generic document would have a \seealso{} or<br>
> something that links to the classes included in one of the method signatures<br>
> for the generic, as a summary. Similarly, the class document would have a<br>
> summary section linking to all generics that have it in a method signature.<br>
<br>
</div>Ooh, I like that idea.<br>
<div class="im"><br>
> For consistency, every method should have a view, and it should be richer<br>
> than simply documenting the method like a function. It could, for example,<br>
> have a \seealso{} to all methods on that generic with signatures that match<br>
> at least one class in its signature. Here "match" would mean not always the<br>
> same class, but a subclass or superclass, as well.<br>
<br>
</div>I like that idea too.<br>
<div class="im"><br>
> For classes, displaying the slots should be optional. Often, that would just<br>
> be an implementation detail. I would say always hide a slot unless<br>
> explicitly asked to make it public. Up for discussion. The class document<br>
> would want to group its methods by generic and collapse them somehow. If<br>
> there is a single method matching the class, briefly list its documentation<br>
> (which somehow includes the generic description). This satisfies the<br>
> class-centric case. If there are multiple methods, list the generic<br>
> description, and available method signatures, with links.<br>
<br>
</div>You mean hiding in the documentation sense, right? Sort of privacy by<br>
convention?<br>
<div class="im"><br></div></blockquote><div><br>Yes.<br> <br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div class="im">
> One last thing: documentation for classes can get pretty long. Is there a<br>
> way to @include extra files? Steve Lianoglou had this idea.<br>
<br>
</div>That's another interesting idea. We currently have @template, which<br>
is a superset of @include, but it might be worthwhile differentiating<br>
them semantically. Where would you imagine such include files living?<br>
Would they be R files or plain text to be interpreted as roxygen<br>
comments? (We decided on R files for templates so that existing<br>
syntax highlighting code would work)<br>
<br></blockquote><div><br>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?<br>
<br> <br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
Hadley<br>
<font color="#888888"><br>
--<br>
Assistant Professor / Dobelman Family Junior Chair<br>
Department of Statistics / Rice University<br>
<a href="http://had.co.nz/" target="_blank">http://had.co.nz/</a><br>
</font></blockquote></div><br>