How to use @inheritParams on single parameters when multiple parameters match?

问题

I would like to document an R function and inherit individual parameter documentation from other functions when multiple parameter names match. For example, lets say I have the following 2 functions.

#' Function 1.
#' 
#' Description of function 1.
#' 
#' @param x XYZ
#' @param y ZYX
#' @return Numeric
fun1 <- function(x, y) {value <- 1}

#' Function 2.
#' 
#' Description of function 2.
#' 
#' @param x ABC
#' @param y CBA
#' @return Numeric
fun2 <- function(x, y) {value <- 2}

I now want to create a third function that inherits parameter x from fun1 and parameter y from fun2. The following do not work:

#' Function 3.
#'
#' Description of function 3.
#'
#' @inherit fun1 params x
#' @inherit fun2 params y
fun3 <- function(x, y) {value <- 3}

#' Function 3.
#'
#' Description of function 3.
#'
#' @inheritParams fun1 x
#' @inheritParams fun2 y
fun3 <- function(x, y) {value <- 3}

If you do the following then both parameters are inherited from fun1:

#' Function 3.
#'
#' Description of function 3.
#'
#' @inheritParams fun1
#' @inheritParams fun2
fun3 <- function(x, y) {value <- 3}

I'm not sure what else to try or if this is even possible?

回答1:

You can use roxygen2 templates for parameters too:

Create a folder called man-roxygen.
Add it to .Rbuildignore by appending a line with ^man-roxygen.
Inside that folder you can create R files with documentation snippets. For instance, let's say you have a file x-arg.R with:
- #' @param x My x parameter.
In all the functions where you want to use the same documentation snippet, write @template x-arg instead of @param bla bla.
Profit.

EDIT: also, you can have more than one @param entry per template if it fits your use case.

I believe this works for pretty much any kind of documentation you want to repeat, though some cases require special handling. For example, if you wanted to have a template with some text that should go under a specific section (e.g. "Details"), the snippet in the R template file must also have the corresponding directive, and then to use it you might need to repeat the directive if you have additional specific text:

In details-template.R

#' @details
#'
#' Text that should appear everywhere

To use it

#' @details
#'
#' Some specific text.
#'
#' @template details-template

来源：https://stackoverflow.com/questions/47782004/how-to-use-inheritparams-on-single-parameters-when-multiple-parameters-match

标签

devtools

roxygen2