Documenting function closures

documentation, r, roxygen2

Solution

One way would be to do something similar to `?family` where you document `g()` and `h()` in the `Value` section of the `.Rd` file. Then provide extended documentation about `g()` and `h()` in a bespoke `\section{foo}`, which you point to in the `Value` section entries for the two functions.

\value{
  Returns an object of class \code{"foo"}, a list with the
  following components:

  \item{g}{function; does foo. See Returned Functions for details.}
  \item{h}{function; does bar. See Returned Functions for details.}
}
\section{Returned Functions}{
  The returned functions do, blah blah...

  \code{g} is defined as

  \preformatted{
  g(x, y, z, ...)
  }

  Arguments are:

  \describe{
    \item{x}{foo}
    \item{y}{foo}
    \item{z}{foo}
  }
}

Whilst roxygen won't be able to do this from the argument `@param`, but you should be able to write this as an arbitrary roxygen section to add to the Rd file. The `Value` section can be written as standard roxygen markup, only the bespoke section would need to be entered literally.

Problem

Suppose I have a function closure in my package, for example ``` f = function(x) { x = x g = function(y) x <<- y h = function() x list(g = g, h = h) } l = f(5) l$g(10) l$h() ``` What is the correct (in the official CRAN sense) way of documenting this function? In particular, - I would like to use `roxygen2` - I would like to provide documentation for the functions `g` and `h`

Original source