R documentation: the @family tag is not working

Question

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: @seealso and @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 @family name should be plural (i.e., “model building helpers” not “model building helper”). You can override the default title by providing a rd_family_title list in man/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

Answer 1

The man/roxygen/meta.R example in the documentation was wrong at the time when you consulted it. The first list level was missing.

In your case it should be:

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

There was also an omission in the code that prevented roxygen2's rd_family_title option from being recognized. All these issues have been fixed in PR 1078 which is included from roxygen2 7.1.1 onwards.