Documenting function closures

Question

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,

1. I would like to use roxygen2
2. I would like to provide documentation for the functions g and h

Answer 1

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.