I've been looking at documenting S4 classes and methods, though I have a feeling many of these issues apply to S3 as well.
My impression is that the documentation system requires or recommends creating basically the same information in several places. I'd like to explain that, see if I'm correct, and suggest that a more automated framework might make life easier. PROBLEM Consider a class A and a method foo that operates on A. As I understand it, I must document the generic function foo (or ?foo will not produce a response) and the method foo (or methods ? foo will not produce a response). Additionally, it appears to be recommended that I document foo in the Methods section of the documentation for class A. Finally, I may want to document the method foo with specific arguments (particularly if if uses "unusual" arguments, but presumably also if the semantics are different in a class that extends A). This seems like a lot of work to me, and it also seems error prone and subject to synchronization errors. R CMD check checks vanilla function documentation for agreement with the code, but I'm not sure that method documentation in other contexts gets much help. To complete the picture, suppose there is a another function, "bar", that operates on A. B extends A, and reimplements foo, but not bar. I think the suggestion is that I go back and add the B-flavored method foo to the general methods documentation for foo. I also have a choice whether I should mention bar in the documentation for the class B. If I mention it, it's easier for the reader to grasp the whole interface that B presents. However, I make it harder to determine which methods implement new functionality. SOLUTION There are a bunch of things users of OO systems typically want to know: 1) the relations between classes 2) the methods implemented by a class (for B, just foo) 3) the interface provided by a class (for B, foo and bar) 4) the various implementations of a particular method All of these can be discovered dynamically by the user. The problem is that current documentation system attempts to reproduce this dynamic information in static pages. prompt, promptClass and promptMethods functions generate templates that contain much of the information (or at least there supposed to; they seem to miss stuff for me, for example saying there are no methods when there are methods). This is helpful, but has two weaknesses. First, the class developer must enter very similar information in multiple places (specifically, function, methods, and class documentation). Second, that information is likely to get dated as the classes are modified and extended. I think it would be better if the class developer could enter the information once, and the documentation system assemble it dynamically when the user asks a question. For example, if the user asks for documentation on a class, the resulting page would be contstructed by pulling together the class description, appropriate method descriptions, and links to classes the focal class extends (as well, possibly, as classes that extend it). Similarly, a request for methods could assemble a page out of the snippets documenting the individual methods, including links to the relevant classes. I realize that implementing this is not trivial, and I'm not necessarily advocating it as a priority. But I wonder how it strikes people. -- Ross Boylan wk: (415) 514-8146 185 Berry St #5700 [EMAIL PROTECTED] Dept of Epidemiology and Biostatistics fax: (415) 514-8150 University of California, San Francisco San Francisco, CA 94107-1739 hm: (415) 550-1062 ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel