generate roxygen from R code?

[kevinushey]

It'd be nice if we could have something like @evalRd, but @evalRoxygen, which takes the output of some R function and treats it as though it were part of the current Roxygen block. For example, suppose you were documenting the same function multiple times, but it took different default arguments in different functions. It'd be nice to be able to write:

## function a
#' @eval roxygen_parameter(default = "foo")

## function b
#' @eval roxygen_parameter(default = "bar")

In this case, roxygen_parameter() is some function defined by the user in the package's namespace, and the output of that function is used to generate the documentation.

[hadley]

And roxygen_parameter() would return a string?

[kevinushey]

Right, it would return a string (or character vector to be joined with newlines). E.g. suppose we had for the above:

roxygen_parameter <- function(default) {
    paste("#' @param db The database to use. Defaults to", default)
}

then, after pre-processing

#' @eval roxygen_parameter(default = "RSQLite")

we would just have

#' @param db The database to use. Defaults to RSQLite.

and then the rest of the roxygen machinery would run as-is.

[hadley]

This will have to work like process_templates() in that the output of the block needs to be parsed (presumably respecting the md flag) and reinserted into the block.

[hadley]

This has to be implemented at a lower-level (i.e. in the parser) than @evalRd and @evalNamespace since it generates roxygen which could potentially belong to any roclet. This means @eval will need to be special-cased into the list of known tags. I think that's ok because we already have special parsing behaviour for the intro block.

This will add recursion to the parsing system, but I think that will only cause problems if you do something crazy like @eval "@eval '@eval'" (I'm not very good at creating quines but you get the idea)

You might argue that @template should go there too. I think that's probably correct, but it would be a bigger change, and I'm not generally that excited about templates anymore.

[kevinushey]

FWIW, I think @eval could effectively subsume any usages of templates. If you think this is the right way to go, we could just make @eval a first-class citizen and later deprecate templates.

E.g. someone who really wanted the template approach could probably do something like this:

roxygen_parameter <- function(default) {
    roxygen_template("man-roxygen/my-template.R", default)
}

where roxygen_template() (name up for debate) would just read the template file, replace values based on the arguments passed in, and return the roxygen text / a parsed roclet / whatever fits best.