Documenting Setter Functions with roxygen

Introduction

In R, setter functions are a useful tool for modifying the attributes of an object without directly accessing its internal structure. However, documenting these functions can be challenging, especially when it comes to generating accurate documentation that is compatible with CRAN’s checks. In this article, we will explore how to document setter functions using roxygen, a popular R package for creating high-quality documentation.

Understanding Setter Functions

A setter function is a special type of function that modifies the attributes of an object. Unlike getter functions, which return the value of an attribute, setter functions assign new values to existing attributes. In R, we can define a setter function using the attr() function, which adds a new attribute to an object or updates its value.

For example, consider the following setter function that adds a unique attribute to any R object:

#' Setter function
#' @param x an R object
#' @param value a character value to set
#' @export
foo<-` <- function(x, value){
    attr(x, 'foo') <- value
    return(x)
}

In this example, the foo<- function takes two arguments: an R object x and a character value value. It adds a new attribute called “foo” to the object x with the value value, and returns the modified object.

Generating Documentation for Setter Functions

While setter functions are useful, they can be difficult to document accurately. This is because the standard way of documenting R functions using Rd files does not directly apply to setter functions. For example, we cannot simply write \usage{ foo(x) <- value } to document the foo<- function.

However, roxygen provides a solution for this problem by introducing a new tag called @usage. This tag allows us to specify the usage information for a function in a format that is compatible with CRAN’s checks.

Here is an example of how we can use the @usage tag to document the foo<- function:

#' Setter function
#' @param x an R object
#' @param value a character value to set
#' @export
foo<-` <- function(x, value){
    attr(x, 'foo') <- value
    return(x)
}

To use the @usage tag, we simply add it to the function documentation before writing the usage information:

#' Setter function
#'
#' Sets a unique attribute on an R object.
#'
#' @param x an R object
#' @param value a character value to set
#' @export
foo<-` <- function(x, value){
    attr(x, 'foo') <- value
    return(x)
}

In this example, the @usage tag is used to specify the usage information for the foo<- function. The usage information includes a brief description of what the function does and the arguments it takes.

Using the `@rdname` Tag

Another useful feature of roxygen is the @rdname tag, which allows us to specify the name of the Rd file that will be generated for our package. When we use the @rdname tag along with the @usage tag, we can generate an accurate and up-to-date documentation for our setter functions.

Here is an example of how we can use the @rdname tag to document the foo<- function:

#' @rdname pattern
#'
#' Sets a unique attribute on an R object.
#'
#' @param value New value
#' @export pattern&lt;-
"pattern&lt;-" <- function(x, value=c("^", "($|(_\\d+(_\\d+)*)$)")){
    attr(x, "pattern") <- value
    x
}

In this example, the @rdname tag is used to specify the name of the Rd file that will be generated for our package. The @usage tag is used to specify the usage information for the function, which includes a brief description of what the function does and the arguments it takes.

Using `@param` Tag

We can also use the @param tag to document the parameters of our setter functions. This allows us to provide detailed documentation about each parameter, including its data type, default value, and usage information.

Here is an example of how we can use the @param tag to document the foo<- function:

#' Setter function
#'
#' Sets a unique attribute on an R object.
#'
#' @param x an R object
#'   The object on which to set the attribute.
#' @param value a character value to set
#'   A new character value to be assigned to the "foo" attribute of the object.
#' @export
foo<-` <- function(x, value){
    attr(x, 'foo') <- value
    return(x)
}

In this example, the @param tag is used to document each parameter of the foo<- function. The documentation includes information about the data type and default value of each parameter, as well as usage information.

Conclusion

Documenting setter functions can be challenging, but roxygen provides a solution for this problem by introducing the @usage, @rdname, and @param tags. By using these tags, we can generate accurate and up-to-date documentation for our setter functions that is compatible with CRAN’s checks.

In conclusion, we hope that this article has provided you with a comprehensive guide to documenting setter functions in R using roxygen. Whether you are new to roxygen or an experienced user, we hope that the examples and code snippets in this article have been helpful in demonstrating how to use the @usage, @rdname, and @param tags to generate high-quality documentation for your setter functions.

Best Practices

Here are some best practices to keep in mind when documenting setter functions using roxygen:

Use the @usage tag to specify the usage information for your function, including a brief description of what the function does and its arguments.
Use the @rdname tag to specify the name of the Rd file that will be generated for your package.
Use the @param tag to document each parameter of your function, including its data type, default value, and usage information.

By following these best practices and using the @usage, @rdname, and @param tags, you can generate high-quality documentation for your setter functions that is compatible with CRAN’s checks.

Last modified on 2025-04-18