I'm writing an R package, and I'd like to include cross references between function documentation.
Following the documentation here, there's a setion that talks specifically about this:
Cross-references
There are two tags that make it easier for people to navigate around your documentation:
@seealsoand@family. [...] If you have a family of related functions, you can use@family {family}to cross-reference each function to every other function within the family. A function can be a member of multiple families.For
sum(), this might look like:#' @family aggregations #' @seealso [prod()] for products, [cumsum()] for cumulative sums, and #' [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.By default
@family {family}, will generate the see also text“Other {family}:”, so the@familyname should be plural (i.e.,“model building helpers”not“model building helper”). You can override the default title by providing ard_family_titlelist inman/roxygen/meta.R:rd_family_title <- list( aggregations = "Aggregation functions" )
So, I've written the documentation of my functions like this:
#' 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
}
(there are about 9 functions I've written this way)
I've also written this meta.R file:
rd_family_title <- list(
a_family = "A family of functions",
another_family = "Another family of functions"
)
This is saved here: [package project path]/roxygen/man/meta.R (again, following the documentation).
However, when I run the document() function (to build the .Rd files), I get the following warnings:
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
And, when browsing the documentation, I see something like this:
[...]
See also
Other a_family: bar(), baz() Other another_family: spam(), eggs()
(I've changed @family {a_family} with @family a_family and I get the same result.
So... What am I missing? Where should the rd_family_title list be? Why is Roxygen failing to replace that "other..." stuff with the titles I've defined?
Some aditional info:
- R version: 3.6.0, running on CentOs 7, and using Rstudio
- Roxygen2 version: 7.0.2
- devtools version: 2.2.1