Package development cycle

2026-02-12

Outline

  • file structures of packages

  • documentation

  • development cycle




Resource: R packages by Hadley Wickham

The Package Development Cycle

  • R packages have rigorous file structures and code requirements

  • R CMD check used to check for adherence: errors, warnings, notes

  • Generally best to start small and extend

devtools package

supports package development

devtools functions operate on active project:

  • document() creates R help files from special comments in the code (roxygen2)

  • install() installs package locally - call with library("pkgname")

  • check() runs R CMD check tests on your package.

File structure

Within folder that has the same name as your R package:

  • DESCRIPTION

  • NAMESPACE

  • R #

  • man

  • data

R code files go into the folder R, data sets go into the folder data, Rd files contain documentation and go into man

DESCRIPTION

plain text file with all the meta information on a package

Package: happyR
Type: Package
Title: What the Package Does (Title Case)
Version: 0.1.0
Author: Who wrote it
Maintainer: The package maintainer <yourself@somewhere.net>
Description: More about what it does (maybe more than one line)
    Use four spaces when indenting paragraphs within the Description.
License: What license is it under?
Encoding: UTF-8
LazyData: true
Imports: package1,package2
Suggests: package3
Depends: package4,package5

Description file reference

Documentation

hello.Rd:

\name{hello}
\alias{hello}
\title{Hello, World!}
\usage{
hello()
}
\description{
Prints 'Hello, world!'.
}
\examples{
hello()
}

Rd is the extension used for R documentation.

Rd files are clearly structured, yet, we DO NOT want to write these ourselves (way too many places to mess up)

The documentation workflow

First: Prep the DESCRIPTION file by adding the line

Roxygen: list(markdown = TRUE)

or use usethis::use_roxygen_md()

  1. Add tags to your .R files in form of roxygen (next slide) comments

  2. Run devtools::document() (or press Ctrl/Cmd + Shift + D in RStudio) to convert roxygen comments to .Rd files.

  3. Preview documentation with ?.

  4. Rinse and repeat 1-3 until the documentation looks the way you want.

Additional help: roxygen2 documentation

Roxygen2

Roxygen comments start with #' to distinguish them from regular comments:

#' Add together two numbers.                         #<- Title 
#'                                                   #<- Free Line
#' This command returns the sum of two numbers. The  #<- Description
#' description can take multiple lines. It ends
#' with a second free line or the start of the 
#' parameters.
#'
#' The second paragraph is optional. It goes into    #<- Details
#' the Details section. 
#' @param x A number.                                #<- Parameters
#' @param y A number.
#' @export                                           #<- Make function visible
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}

Roxygen2 and NAMESPACE

@export, @import, @importFrom do not write anything into the help file
instead, they write to NAMESPACE

  • @export makes the function visible to package users

  • @import makes the imported package visible to the function code so you don’t have to use package::function() notation

  • @importFrom makes the imported function from the specified package visible (a more limited version of @import) my personal favorite

Roxygenized example in add.Rd

% Generated by roxygen2 (4.0.0): do not edit by hand
\name{add}
\alias{add}
\title{Add together two numbers}
\usage{
add(x, y)
}
\arguments{
  \item{x}{A number}

  \item{y}{A number}
}
\value{
The sum of \code{x} and \code{y}
}
\description{
Add together two numbers
}
\examples{
add(1, 1)
add(10, 1)
}

Your Turn

  • Delete the file hello.Rd in the folder man

  • Prep the DESCRIPTION file by adding the Roxygen tag.

  • Include roxygen comments for the function hello() in the file hello.R to create the same help for hello as was there before.

  • Run devtools::document() to create the file hello.Rd.

  • Build the package and run ?hello.

  • Already done? Expand the functionality of hello to produce an output of Hello, string! for hello(string). Update ?hello accordingly.

Roxygen tags

Tag Purpose
@export Make the function visible to users of the package
@param Describe inputs
@return Describe outputs
@examples Show how the function works
@author Who wrote the function (if different from package)
@seealso Pointers to related functions
@aliases Make it easier for users to find
@rdname Useful for functions that are invalid filenames and for combining docs
@import Call all functions from another package natively (without package::function)
@importFrom Call a single function from another package natively

Commands in Roxygen

Most of these elements can also be replaced by markdown

Tag Purpose
\code{} Discuss R code — backticks work here as well
\link{} Make link to another function (usually wrapped in \code{})
\eqn{} Inline equation (standard LaTeX)
\emph{} Italic text — or use * at the beginning and end
\strong{} Bold text — or use ** at the beginning and end

Numbered list (Use \itemize{} for bulleted):

\enumerate{
  \item First item
}

Your Turn

  • Expand the functionality of hello to produce an output of Hello, string! for hello(string).

  • Insert the corresponding roxygen tags to expand on the documentation

  • Run devtools::document()

  • Check that the help for hello is updated