Документация R: тег @family не работает - PullRequest
Новая
       11

Документация R: тег @family не работает

1 голос
/ 02 марта 2020

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

Следуя документации здесь , есть раздел, который конкретно говорит об этом:

Перекрестные ссылки

Существуют два тега, облегчающие пользователям навигацию по вашей документации: @seealso и @family. [...] Если у вас есть семейство связанных функций, вы можете использовать @family {family} для перекрестной ссылки каждой функции на каждую другую функцию в семействе. Функция может быть членом нескольких семейств.

Для sum() это может выглядеть следующим образом: 

#' @family aggregations
#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and
#'   [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.

По умолчанию @family {family}, сгенерирует см. Также текст “Other {family}:” поэтому имя @family должно быть во множественном числе (т. е. “model building helpers” не “model building helper”). Вы можете переопределить заголовок по умолчанию, предоставив список rd_family_title в man/roxygen/meta.R: 

rd_family_title <- list(
 aggregations = "Aggregation functions"
)

Итак, я написал документацию по моим функциям следующим образом: 

#' My foo function
#'
#' Does something with my data.
#'
#' Lorem ipsum.
#'
#' @param .data A data frame.
#' @return My processed data.
#' @usage
#' my_foo_function(.data)
#' @family {a_family}
#' @family {another_family}
#' @export
my_foo_function <- function(.data) {
# Some code
}

(есть около 9 функций, которые я написал таким образом)

Я также написал этот meta.R файл: 

rd_family_title <- list(
  a_family = "A family of functions",
  another_family = "Another family of functions"
)

Это сохранено здесь: [package project path]/roxygen/man/meta.R (опять же, следуя документации).

Однако, когда я запускаю функцию document() (для создания файлов .Rd), я получаю следующие предупреждения: 

document()
## Updating my_package documentation
## Writing NAMESPACE
## Warning messages:
## 1: Unknown Roxygen options a_family, another_family.
## Supported options: roclets, load, old_usage, markdown, r6, package

И , просматривая документацию, я вижу что-то вроде этого:

[...]

См. также

Другое a_family: bar (), baz () Другое other_family: spam (), eggs ()

(я изменил @family {a_family} с @family a_family и получаю тот же результат.

Итак ... Что такое Я пропустил? Где должен быть список rd_family_title? Почему Roxygen не удается заменить этот "другой ..." на названия, которые я определил?

Некоторая дополнительная информация:

  • R версия: 3.6.0, runni нг на CentOs 7 и с использованием Rstudio
  • версия Roxygen2: 7.0.2
  • версия devtools: 2.2.1
...