roxygen2
roxygen2 copied to clipboard
r-lib
Documenting multiple R6 (sub)classes in same file
In the arrow package, we have lots of R6 classes, so we're excited to see the new support for R6 in roxygen2. Because we have so many classes, in our current doc setup, we've grouped some into the same file, as you might do with similar functions. This is particularly useful for sibling subclasses that don't differ much.
With the latest roxygen2, this doesn't work so well. Every class gets its own "Super classes" and "Methods" sections, with no obvious distinction among them.
Instead of condensing information and reducing duplication, it's all duplicated in the same file.
Is it a bad idea to try to document these classes in the same file? I.e. do you view this as intended behavior or a feature not yet implemented?
I don't think we thought that far ahead, so we'd love to hear your thoughts on how this should work.
So, one simple way to do this would be to have the same content, but change the headings to include the class name, plus have a table of contents at the top of the page that includes all classes. Is that good enough?
That would be an improvement, but I'm not sure it's good enough. What I have in mind is more like: think about each method subsection as if it were its own man page, and you could #' @rdname ClassName$method to group together similar methods, with the usage/arguments/etc. sections integrated like they were regular functions. With multiple R6 classes in the same file, you could automatically group by $method name and not require an explicit @rdname to bundle them, but have that available to override the default or to allow you to group together another function that isn't an R6 method but that is a convenience wrapper around one.
Would it help if I mocked up an example?
Is this what the other arrow bindings have? You can also just point to one of them I guess.
That's not exactly what we do currently, in part because it's very tedious and manual to document R6 classes prior to the new roxygen2 (as you well know).
Here's one example:
- https://arrow.apache.org/docs/r/reference/InputStream.html is one file we currently have where a bunch of similar subclasses are grouped.
- https://github.com/apache/arrow/blob/master/r/R/io.R#L129-L223 is the source, very manually assembled.
- https://enpiar.com/arrow-r-site/reference/InputStream.html is what the new roxygen2 does to that, without any changes to the inline docs
- https://enpiar.com/arrow-r-site/reference/InputStream2.html is a version I hand-edited to mock up something more like I'd want. Each method section would essentially behave like its own man page, with description, usage, arguments, return value, etc.
That's not exactly what we do currently, in part because it's very tedious and manual to document R6 classes prior to the new roxygen2 (as you well know).
Sry, I meant other languages than R.
Oh, well, I wouldn't call the C++ docs the most elegant, and they take a different approach altogether in organizing information, more single page. E.g. https://arrow.apache.org/docs/cpp/api/datatype.html