Guidance on documenting R6

[sckott]

to add maybe to 1.7 Documentation in chapter 1 Packaging Guide.

Because roxygen2 doesn't currently completely/sufficiently document R6 methods, I think we should give some guidance on this, just a few tips to better document your R6 stuff so users have as much info as possible.

A brief start:

---

Documenting R6

This is assuming the maintainer is using roxygen2.

Usage

That "Usage" section at the top of most manual pages for R functions is not created for R6 classes. To create that section for your R6 class' new method, we suggest doing the following:

#' @section Usage:
#' ```
#' FooBar$new(x, y, z, ...)
#' ```

The downside of this approach is that normal usage sections are checked during R CMD CHECK - but not with the above approach. But otherwise its not created at all or you get something that's not useful to users (see below). Remember to make sure your Usage section is up to date with what the R6 class' initialize method contains.

Methods

You should document all public methods on your R6 class so users know how to use each method.

#' @section Methods:
#'   \describe{
#'     \item{`multiply()`}{
#'       Multiply something
#'     }
#'   }

method with parmeters, can describe each within \itemize{\item ...}

#' @section Methods:
#'   \describe{
#'     \item{`multiply(x, y)`}{
#'       Multiply two numbers
#'       \itemize{
#'         \item some number
#'         \item some number
#'       }
#'     }
#'   }

Other pieces

Folks documenting R6 classes usually also do:

#' @format NULL
#' @usage NULL

Setting @format to not be used because it creates something not very useful:

An object of class R6ClassGenerator of length 24

See above for why @usage is removed.

[sckott]

anyone have thoughts?

[maelle]

What a good idea! I have no thought on the content itself.

[noamross]

I don't use R6 enough myself to know though I really like having this. Maybe ping the Slack channel?

[sckott]

• Jonathan Sidi suggested the approach he uses https://github.com/yonicd/carbonate/blob/master/R/carbon.R
• Phillipp Ottolinger suggested https://github.com/mlr-org/mlr3/wiki/Roxygen-Guide

[coolbutuseless]

I think a tabular environment for the method arguments renders much nicer than an itemize. e.g.

\tabular{ll}{
  arg1  \tab  arg1 description \cr
  arg2  \tab  arg2 description \cr
}

I also think a detailed \preformatted{} usage section gives a really good overview of the available methods - as done in {processx} https://github.com/r-lib/processx/blob/bc7483237b0fbe723390cbb74951221968fdb963/R/process.R#L2

[paleolimbot]

I once wrote a hack-job documenter that uses @eval and python-style docstrings, which can be extracted by looking for the first atomic in body(fun). There are some pretty severe limitations to the @eval approach (can only contain a single section and all text must be a single paragraph...both of which were discovered by trial and error), but the docstring approach is really nice for keeping the documentation next to the function definition. In my dreams the @param tags could be used in a docstring, but that would probably need some custom trickery. Roughly, it might look like this:

#' Convert between data spaces
#'
#' Class documentation
#'
#' @eval r6doc("Scale")
#'
#' @eval r6inherits("ScaleNull")
#'
#' @export
Scale <- R6Class(
  "Scale",
  public = list(
    aesthetics = NULL,
    guide = NULL,

    initialize = function(aesthetics = character(0)) {
      "
      Create a Scale object representing zero or more `aesthetics`.
      "
      ...
    }
  )
)

Code implementing is here: https://github.com/paleolimbot/ggr6/blob/master/R/r6doc.R

An R6 class documented in this way is here: https://github.com/paleolimbot/ggr6/blob/master/R/scale.R (rendered here: https://paleolimbot.github.io/ggr6/reference/Scale.html )

[gaborcsardi]

I am not sure that a one size fits all approach is appropriate here. Some classes are small, and can be documented in a single manual page. Others need individual manual pages for at least some methods. Some need additional manual pages for some groups of methods.

[sckott]

thanks @coolbutuseless - will try that out

[sckott]

thanks @paleolimbot - hadn't seen that approacy yet. Is there a way to define parameters?

[sckott]

good point @gaborcsardi We will for sure make that point that it depends and suggest different approaches for different situations

[paleolimbot]

@sckott - The way I've written it, there's no support for anything except a single line of text. I think that with @param and @rdname implemented, the text could be processed to fit a number of the above suggestions.

[sckott]

okay, thanks

[sckott]

started drafting the new section afbb9e9