Using @inheritParams to Inherit Parameters from Multiple Functions

When working with R documentation using the roxygen2 package, you often find yourself in a situation where you want to document multiple functions that share similar parameters. While @param allows you to specify parameter documentation for individual functions, it can become cumbersome when dealing with multiple functions that have overlapping or identical parameter names.

In this article, we will explore how to use the @inheritParams directive to inherit parameter documentation from multiple functions when their parameter names match.

Background

The roxygen2 package provides a powerful way to generate R documentation using R source code. One of its features is the ability to create templates for common documentation elements, such as parameter descriptions or function summaries. These templates can be reused across multiple functions, making it easier to maintain consistent documentation styles.

The Problem

Suppose you have two functions, fun1 and fun2, each with a set of parameters that you want to document using the same approach:

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

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

You want to create a third function, fun3, that inherits parameter documentation from both fun1 and fun2. The problem is that @inheritParams directives do not work as expected when multiple parameters match between functions.

Attempting to Use @inheritParams

Let’s try using the @inheritParams directive with fun1 and fun2 separately:

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

Unfortunately, this approach does not work as expected. Both x and y parameters are inherited from fun1, resulting in incorrect documentation.

Using @inheritParams with Multiple Functions

To overcome the limitations of the previous approach, you can use roxygen2 templates for parameter documentation. Here’s a step-by-step guide to create a solution:

Creating a Template Folder

Create a new folder called man-roxygen in your project directory and add it to your .Rbuildignore file.

Defining a Parameter Template

Inside the man-roxygen folder, create an R file named x-arg.R. This template will contain parameter documentation for x.

#' @param x My x parameter.

This is just a basic example. You can customize this template to fit your needs.

Applying the Template to Multiple Functions

In all functions where you want to use the same documentation snippet, include the @template directive instead of @param.

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

Repeat this approach for each function that requires the same parameter documentation.

Inheriting Parameter Documentation from Multiple Functions

To inherit parameter documentation from multiple functions when their parameter names match, use the following syntax:

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

This approach works by applying the @template directive to a parameter that has already been defined in another function. The documentation from the template is then inherited by the current function.

Special Cases

Some cases may require special handling when using templates for parameter documentation. For example, if you want to include additional text under a specific section (e.g., “Details”), you need to repeat the corresponding directive in both the R template file and the function that uses it.

#' @details
#' Text that should appear everywhere

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

In this case, you need to include the @template directive in the details-template.R file as well.

Conclusion

Using @inheritParams with multiple functions when their parameter names match can be challenging. However, by creating a template folder and defining parameter templates for common documentation elements, you can overcome these limitations. This approach provides a flexible and reusable way to maintain consistent documentation styles across your project.

Last modified on 2024-08-17