Tag to auto-generate tidyeval section

[hadley]

I think it should look something like:

#' @usesTidyEval a, ...

which would generate:

#' @section Tidy evaluation:
#'
#' This function uses tidy eval, a consistent approach to NSE used throughout
#' the tidyverse. Learn more at <...>. 
#'
#' The following arguments are quoted:
#' * `a`
#' * `...`

cc @lionel- @jennybc

[lionel-]

How about:

• @quotedParams name1, name2, ...
• @quotedParam name optional_unquoted_value

#' @quotedParams foo, bar
#' @quotedParam baz
#' @quotedParam qux A character vector of column names or an integer vector of column positions.

This would generate:

#' The following list of arguments are quoted. They all support
#' quasiquotation and unquoting of R code (symbols, expressions,
#' quosures). They should also support unquoting of actual values.
#' in which case the type of accepted values is indicated alongside
#' the parameter:
#'
#' * `foo`
#' * `bar`
#' * `baz`
#' * `qux`: A character vector of column names or an integer vector of column positions.

[hadley]

Why wouldn't that be documented with @param?

[lionel-]

Then we have to mention in @param that the parameter is quoted and supports quasiquotation, which seems to be redundant with that section.

[hadley]

What if we inlined the bulleted list and automatically added "[quoted, see below]" to the parameter text.

#' This function uses the [tidy evaluation](...) framework for NSE. 
#' Arguments `foo`, `bar`, `baz`, and `quz` are quoted. They support
#' quasiquotation and unquoting of R code (symbols, expressions,
#' quosures). They should also support unquoting of actual values.
#' in which case the type of accepted values is indicated alongside
#' the parameter. See <...> for details

[lionel-]

That would be a nice solution.

[hadley]

#' @section Tidy evaluation:
#'
#' This function uses the [tidy evaluation](...) framework for NSE. 
#' Arguments `foo`, `bar`, `baz`, and `quz` are quoted. This means
#' that support quasiquotation, allowing you to unquote R code (symbols, 
#' expressions, quosures) using `!!` and `!!!`. 
#' 
#' Learn more at  <...>.

[hadley]

Feels like this really needs to be wrapped up in some general system for type/effect annotations so that we don't special case tidyverse conventions inside roxygen2.

[jennybc]

Also, since this thread was last active, we got usethis::use_tidy_eval(), which addresses the problem from a different angle.