In jr-packages/jrPackage: Jumping Rivers: Building an R Package

Documentation

Using roxygen2 simplifies documentation\sidenote{The first package I wrote didn’t use \textbf{roxygen2} and it was a very painful experience.}. The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in the man/ directory. In theory, you should never directly edit the Rd files.

Tasks

1. Copy the following roxygen2 descriptions to your add() function

r #' @title A function for adding #' #' @description A really good adding function. #' Perhaps the best function ever! #' #' A work of pure genius. #' @param x a number #' @param y another number #' @return a number #' @export #' @examples #' add(5, 10) #' ## Can also use negative numbers #' add(-5, 10) add = function(x, y) { if (!check_numeric(c(x, y))) stop("Not numeric") x + y }

1. Rebuild your package and look at the help file for the add() function, i.e. ?add . Run the examples via \begin{table}[b] \centering \begin{tabular}{@{} ll} \toprule Tag name & Description \ \midrule \texttt{@title} & Short title for documentation page. \ \texttt{@description} & Longer description page. Skip a line for a \ &\qquad new paragraph.\ \texttt{@param} & Function parameter description. \ \texttt{@inheritParams} & Use the parameter definition from another function. \ \texttt{@export} & Add the function to the \texttt{NAMESPACE} file.\ \texttt{@return} & What does the function return, e.g. a data frame. \ \texttt{@examples} & Function examples (will be run when building). \ \texttt{@rdname} & Point multiple functions to the same help file,\ & \qquad e.g. \texttt{?substr}. \ \texttt{@seealso} & Pointers to other documentation pages. \ \texttt{@importFrom} & Import functions from other packages. \ \bottomrule \end{tabular} \caption{Useful \textbf{roxygen2} tags for documenting functions.}\label{T1.1} \end{table} r example(add)

2. Add a help page for the subtract() function\sidenote{Install and restart.}.

3. Create a function called multiply() and add an associated help page\sidenote{Install and restart.}.

4. Create a function called times()

r times = function(x, y) multiply(x, y)

Export the times() function\sidenote{Install and restart.}.

1. Use the @rdname tag above the times() function to point to the multiply() help page, i.e.

r #' @rdname multiply

Install and restart. Look at ?multiply and ?times. Now add \newline{\texttt{@examples} to the \texttt{times()} function.} Look at the new times() help \newline{page.}

Importing functions

We often want to use functions from other R packages. When we do this we need to be explicit, i.e. state what we want and from where. The great thing about R packages, is that when we install a package, the dependencies are also automatically installed.

Tasks

1. Install the package jrPackage. First, we need the drat package r install.packages("drat") Then we add the rcourses repo\sidenote{Run the \texttt{.libPaths()} function to see the repository location.} r drat::addRepo("jr-packages") \noindent{Then install as usual} r install.packages("jrPackage")

2. The jrPackage contains a very useful function called div() that we want to use

r library("jrPackage") div(10, 2) \noindent{To use the \texttt{div()} function within our package, we have to import it first} r #' @importFrom jrPackage div \noindent{and add an entry to the \texttt{DESCRIPTION} file}

Imports: jrPackage

Create a function divide() that uses the div() function.

The DESCRIPTION file

The DESCRIPTION file contains high level information about your package. For example, the package name, a brief description, the licence, and your email address.

\indent{Open the \texttt{DESCRIPTION} file and update fields with relevant information. An example is given below.}

Package: pkg
Type: Package
Title: My First package
Version: 0.1
Date: 2016-11-01
Authors@R: person(given="Colin", family="Gillespie",
email="[e-mail]", role = c("aut", "cre"))
Maintainer: Colin Gillespie <[e-mail]>
Description: This is my very first package. It contains
exceedingly useful functions, such as add and subtract.
Make sure you add a couple of spaces to indent the
Description otherwise you will waste hours of your life
trying to find the bug.
License: GPL-2 | GPL-3
LazyData: TRUE

Package checks

One of great things about R packages, is that there are a number of package checks that are available. These include

• Checking the syntax of the DESCRIPTION and NAMESPACE file.

• Checking your examples run.

• Checking all exported functions are documented.

Tasks

1. Run the standard package checks on your package, via

Build -> Check Package

Check that you package passes all tests\sidenote{CTRL + E.}. Fix any errors, warnings \newline{or notes.}

1. Add the following example to the add() function

r #' add("A", "B")

Build the package. Does the package still build? Check the \newline{package. Does the package pass all tests?}

jr-packages/jrPackage documentation built on Dec. 4, 2020, 8:27 a.m.