Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

generate roxygen from R code? #645

Closed
kevinushey opened this issue Aug 4, 2017 · 5 comments
Closed

generate roxygen from R code? #645

kevinushey opened this issue Aug 4, 2017 · 5 comments
Labels

Comments

@kevinushey
Copy link
Contributor

@kevinushey kevinushey commented Aug 4, 2017

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 hadley added the feature label Aug 16, 2017
@hadley
Copy link
Member

@hadley hadley commented Aug 16, 2017

And roxygen_parameter() would return a string?

@kevinushey
Copy link
Contributor Author

@kevinushey kevinushey commented Aug 16, 2017

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
Copy link
Member

@hadley hadley commented Aug 18, 2017

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
Copy link
Member

@hadley hadley commented Aug 18, 2017

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
Copy link
Contributor Author

@kevinushey kevinushey commented Aug 18, 2017

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.

hadley added a commit that referenced this issue Aug 18, 2017
@hadley hadley mentioned this issue Aug 18, 2017
@hadley hadley closed this in #652 Aug 18, 2017
hadley added a commit that referenced this issue Aug 18, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants