Editing documentation

Basics

One of the benefits of using R packages, is that help files can provide useful guidance on function arguments, and details about the steps or assumptions of the function.

This is standard fare for any R user:

library(ggplot2)
help(geom_point) # or ?geom_point

As a developer, we generate these help files by using a handy package called Roxygen2, which lets us put all the documentation in specially formatted comments right above the associated function in .R files.

Example:

#' @title Add
#'
#' @description Add together two numbers
#'
#' @param x \[`numeric(1)`\] \cr A number
#' @param y \[`numeric(1)`\] \cr A number
#'
#' @return The sum of `x` and `y`
#'
#' @examples
#' add(1, 1)
#' add(10, 1)
#'
#' @export
add <- function(x, y) {
  x + y
}

Once you've saved this file with the Roxygen header, you can use the devtools::document() function to build .Rd files which are automatically saved to the man folder in your package structure. Then, preview the documentation by doing ?function_name or help(function_name).

Each @ in the header is called a tag. Go here to learn more about which tags exist.

Tips and best practices

Using markdown syntax

The ihmeuw-demographics R packages are set up to use Roxygen2 with markdown support. This makes it much easier to include links, format code, lists, etc.

Equations

Equations can be helpful to mathematically document what a function is doing. The eqn and deqn Roxygen functions can be used to display equations but complicated latex equations will only properly render on the pkgdown site and not the function help documentation.

For the ihmeuw-demographics R packages we use latex syntax for functions where complicated equations are important to display correctly, like nSx_from_lx_nLx_Tx(), but for simpler equations we do not use latex syntax so that the equations are easy to interpret in the help documentation or the pkgdown site, like generating the lifetable parameters.

Order of tags in function headers

We suggest to include all tags in the order they appear in rendered help pages, followed by...

@import
@export
@rdname

as appropriate.

Indentation in function blocks

#' @description example description extending over multiple
#'   lines. This is option 1: start description after tag
#'   and indent next line by two spaces.
 
#' @description
#' Example description extending over multiple lines. This is
#' option 2: start description on new line after tag. In this
#' case there's no need to indent by two spaces on new lines.

Describing argument types

Each argument should describe the expected type of variable (for example a single integer(1) vs an integer vector of any size integer() vs a data.table data.table()). The \cr creates a new line.

#' @param x \[`numeric(1)`\] \cr 
#'   A number
#' @param y \[`numeric(1)`\] \cr 
#'   A number

Other tips

• Use @inheritParams tag to copy arguments from one function to another. Reduces duplicated @param tags.
• When referencing function arguments in documentation use backticks to format like code. example_arg.
• When referencing possible function argument values use single quotes. 'example_arg_value'.
• When combining the function arguments and their values do something like 'col_stem_start'.
• To have a single help page cover multiple functions, use the @rdname tag.

pkgdown site

A pkgdown site is a website compiled to summarize and interface with your R package, it's directory, and vignettes. Our repositories use github actions to regularly deploy the updated pkgdown site everytime the master branch of a repo is updated. The url of the deployed site is https://ihmeuw-demographics.github.io/<package_name>.

When you are developing a package in Rstudio, use:

• pkgdown::build_reference() to build the documentation for functions, data, etc. that is saved in the man directory
• pkgdown::build_articles() to build the vignettes
• pkgdown::build_site() to build the complete site
• pkgdown::preview_site() to just preview the site after it has already been built