Documenting ggplot2 Statistic Extension with roxygen2 and devtools: Mastering the @rdname Tag

Documenting a ggplot2 Statistic Extension - devtools::document() is not creating packagename-ggproto.Rd

In this article, we will explore the process of documenting a ggplot2 statistic extension using roxygen2 and devtools. We will cover how to use the @rdname tag correctly and when to use it.

What are roxygen2 and devtools?

roxygen2 is an R package that provides a set of tools for building documentation for R packages. It includes several features such as automatic generation of documentation files, support for R Markdown and HTML documentation, and integration with RStudio’s editor.

devtools is another popular R package that provides a set of tools for building and managing R packages. It includes features such as creating and managing package sources, building and releasing packages, and integrating with roxygen2 for generating documentation.

The Problem

In the given example, we are trying to document a ggplot2 statistic extension using devtools::document(). However, the function add is already documented in the same file. We can’t use @rdname to link the function times with an existing file.

Solution 1: Using the `@name` Tag

To solve this problem, we need to create a dummy function using the @name tag and then document other functions in that same dummy file using @rdname.

Here’s how you can do it:

#' Basic arithmetic
#'
#' @param x,y numeric vectors.
#' @name arith
NULL

#' @rdname arith
add <- function(x, y) {
  # Add implementation here
}

#' @rdname arith
times <- function(x, y) {
  # Times implementation here
}

Solution 2: Using the `@name` Tag with roxygen2 Vignettes

If you’re using roxygen2 for your documentation, you can use the @vignette tag to create a vignette file that documents all of your functions.

Here’s an example:

#' Create a new ggplot2 statistic extension
#'
#' @importFrom ggplot2 geom_point

statistic_extension <- function(x) {
  # Return implementation here
}

#' @export
statistic_extension

Conclusion

In this article, we’ve explored the process of documenting a ggplot2 statistic extension using roxygen2 and devtools. We’ve covered how to use the @rdname tag correctly and when to use it.

When creating documentation for your R package, remember that you need to create a dummy function using the @name tag if you’re linking functions with an existing file or vignette. If you’re not building a documentation file around a single function, you can simply document other functions in the same file.

By following these tips and best practices for documenting your R package, you’ll be able to provide clear and concise information about your code that will help users understand how to use it correctly.

Last modified on 2025-03-06