Help files with R packages

Developing R Packages

Jasmin Ludolf

Content Developer

R package structure

Example package structure

Help files for functions

Order of help file components

Title
Description

use_package help

Help files for functions

Order of help file components

Title
Description
Usage
Arguments

use_package help

Help files for functions

Order of help file components

Title
Description
Usage
Arguments
Returns and/or See Also
Examples

use_package help

roxygen2 headers for Title and Description

Header text following #' appears above the function definition

#' Depend on another package
#'

#' `use_package()` adds a CRAN package dependency to `DESCRIPTION` and offers a
#' little advice about how to best use it. `use_dev_package()` adds a
#' dependency on an in-development package, adding the dev repo to `Remotes` so
#' it will be automatically installed from the correct location.

Usage and roxygen2 header for Arguments

use_package(package, type = "Imports", min_version = NULL)

#' @param package Name of package to depend on.
#' @param type Type of dependency: must be one of "Imports", "Depends",
#'   "Suggests", "Enhances", or "LinkingTo" (or unique abbreviation). Matching
#'   is case insensitive.

#' @param min_version Optionally, supply a minimum version for the package.
#'   Set to `TRUE` to use the currently installed version.

#' @param remote By default, an `OWNER/REPO` GitHub remote is inserted.
#'   Optionally, you can supply a character string to specify the remote, e.g.
#'   `"gitlab::jimhester/covr"`, using any syntax supported by the [remotes
#'   package](
#'   https://remotes.r-lib.org/articles/dependencies.html#other-sources).

roxygen2 headers for Returns and See Also

From unitConverter:

#' @returns A numeric temperature value in the unit specified as `unit_to`.

From use_this:

#' @seealso The [dependencies
#'   section](https://r-pkgs.org/description.html#dependencies) of [R
#'   Packages](https://r-pkgs.org).
#'

Exported versus non-exported functions

Exported functions:

Loaded with the package
Call use_packag() directly after library() call
Documented in help files
Core package functionality

Non-exported functions:

Called with :::
May be documented
Support exported functions

How to export a function

Be default, functions are not exported
Previously: unitConverter:::temp_converter()

#' @export

Examples

#' @examples
#' \dontrun{
#' use_package("ggplot2")
#' use_package("dplyr", "suggests")
#' use_dev_package("glue")
#' }

Let's practice!

Developing R Packages