I'm developing a new, relatively complex, R package right now. It's been a while since I've done so and had more recently been doing a lot of C++ programming with Doxygen. I've found manually maintaining Rd files to be a real pain, and was really happy to find Roxygen.
For the most part, packages that I've written (and am currently writing) have complex classes that store and process a large amount of data. There are usually many generics with only a single method each. The xcms package has several such classes: http://www.bioconductor.org/packages/release/bioc/html/xcms.html For that package, some of of the methods were so simple that the method/generic documentation was kept in the class itself, which would add a type of documentation to the list below. More complex methods got their own page. I have some code written for class documentation which pulls method descriptions in during the roxygenize() call. I haven't pushed that out to Github yet because I'm waiting on how my other pull request goes. :-) Cheers. -Colin > Hi all, > > I've been spending some time thinking about how to document S4 > methods, and I've included my current thoughts so far. I'd really > appreciate your feedback, so we can get roxygen2 working well with S4. > > # Methods > > Two types of generics: > > * Large number of simple methods such as in the Matrix package. All methods > have the same arguments with the same meaning and no `...`. Often dispatch > on multiple parameters, leading to a combinatorial explosion of methods. > This also includes methods like `length` which many classes implement, but > are typically intuitive and need little explanation. > > Methods are only listed in the generic so you know what is available. > > Method look up goes directly to the generic. > > * Small number of complex methods, where each method needs individual > documentation. This includes methods like `print`, where different classes > have different arguments. Similarly, model methods like `predict` and > `anova` typically need documentation for individual methods because that's > where it is most appropriate to describe the statistical operation. > > Methods are listed in the generic along with a brief description and a > pointer to more information. They have their own topics and method lookup > goes to individual methods. > > This style of method seems to be somewhat more prevalent in S3. > > The user should be able to switch between these two types of documentation: > > * if method only has description, defaults to including in generic > * if method has anything more than a description, gets own file. > > Question: should all methods get their own file? If yes, then what > should the name/alias for the topic be because the main alias should > be in the generic. > > # Generics > > Generics use `\Sexpr{}` to dynamically list method descriptions from > other locations at render time. Uses `findMethods()` to find all > methods corresponding to the generic, then determines the topic name > for each method, then determines the Rd file name, then extracts the > description for each Rd file. (Will need to exclude methods already > documented in the generic). All methods documented in a given topic > are grouped together. > > Methods should be listed in a `Methods` section, sorted by signature. > > # Classes > > Similarly, class uses `\Sexpr{}` to pull in minimal method description > for all class methods. Also need `\Sexpr{}` macro to list all > subclasses of the class. See `class?diagonalMatrix` for a good > example. Class should have slots, which by default is a list of slot > names and their known prototypes. Optionally overridden by the user > with `@slot` tag. > > Hadley _______________________________________________ Roxygen-devel mailing list Roxygen-devel@lists.r-forge.r-project.org https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel
