Как использовать @inheritParams по отдельным параметрам, когда несколько параметров совпадают?

Я хотел бы задокументировать функцию R и наследовать отдельную документацию по параметрам от других функций при совпадении нескольких имен параметров. Например, скажем, у меня есть следующие 2 функции.

#' 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}

Теперь я хочу создать третью функцию, которая наследует параметр x от fun1 и параметр y от fun2. Следующие не работают:

#' 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}

Если вы выполните следующее, оба параметра наследуются от fun1:

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

Я не уверен, что еще попробовать или если это возможно?

ОТВЕТЫ

Ответ 1

Вы также можете использовать шаблоны roxygen2 для параметров:

  • Создайте папку с именем man-roxygen.
  • Добавьте его в .Rbuildignore, добавив строку с ^man-roxygen.
  • Внутри этой папки вы можете создавать R файлы с фрагментами документации. Например, допустим, у вас есть файл x-arg.R с:
    • #' @param x My x parameter.
  • Во всех функциях, где вы хотите использовать один и тот же фрагмент документации, пишите @template x-arg вместо @param bla bla.
  • Прибыль.

РЕДАКТИРОВАТЬ: также, вы можете иметь более одной записи @param на шаблон, если это соответствует вашему @param использования.

Я считаю, что это работает практически для любой документации, которую вы хотите повторить, хотя в некоторых случаях требуется особая обработка. Например, если вы хотите иметь шаблон с текстом, который должен находиться в определенном разделе (например, "Детали"), у фрагмента в файле шаблона R также должна быть соответствующая директива, а затем для его использования вам может потребоваться повторите директиву, если у вас есть дополнительный конкретный текст:

В details-template.R

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

Использовать его

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