4  Documentation

Recording

Write function documentation using the roxygen format. This is what creates the help documentation for functions.

Packages required for this chapter
library(devtools) # for rendering documentation and loading your package
Loading required package: usethis

4.1 Roxygen

Go to the R/apa_t_pair.R file we created last week. Put your cursor anywhere inside that function and choose Insert Roxygen Skeleton from the Code menu. It should generate documentation code in roxygen format like this:

#' Title
#'
#' @param x
#' @param y
#' @param dv
#' @param level1
#' @param level2
#'
#' @return
#' @export
#'
#' @examples

This creates the help files you can see for any function. For example, type ?t.test in the console.

4.1.1 Title and Description

The first line of the roxygen documentation is the title and the paragraph under that is the description. If you have more than one paragraph of description, you need to add the @description tag. Update your documentation like this:

#' APA text for Paired-Samples T-Test
#' 
#' @description
#' Create APA-formatted text for the results of an independent-samples t-test in the following format:
#'
#' A paired-samples t-test was conducted to compare \{dv\} between \{level1\} (M = \{mean1\}, SD = \{sd1\}) and \{level2\} (M = \{mean2\}, SD = \{sd2\}). There was a \{non\}significant difference; t(\{df\}) = \{t_value\}, p = \{p_value\}.
Note

The curly brackets need to be prefaced by a backslash so they will show as literal curly brackets in the Help files, rather than be interpreted as markdown syntax.

4.1.2 Arguments

The “Arguments” section is created from the lines that start with @param. They should define each argument in the function.

#' @param x A vector of the values for level 1.
#' @param y A vector of the values for level 2.
#' @param dv The text describing the DV in the output statement.
#' @param level1 The text describing level 1 in the output statement.
#' @param level2 The text describing level 2 in the output statement.

4.1.3 Return Value

The line starting with @return creates the “Value” section. This tells the user what kind of object is returned from the function. The line @export tells the package that this is a function you want others to be able to use; if you omit this, the function will only be available internally to your package.

#' @return A character string.
#' @export

4.1.4 Examples

Add at least one example that shows how the function works. Make sure to create any objects you need to run the function. Here, we can use the data object self_res_att because we added it to our package in Chapter 2.

#' @examples
#' # use generic text
#' apa_t_pair(x = self_res_att$f_self,
#'            y = self_res_att$f_non)
#'
#' # specify the text for dv and levels
#' apa_t_pair(x = self_res_att$f_self,
#'            y = self_res_att$f_non,
#'            dv = "preferences for female faces",
#'            level1 = "participants who resembled those faces",
#'            level2 = "non-self participants")

4.2 Helper Functions

Not everyone documents helper functions like round0, but I think it’s good practice. Repeat the steps above with round0, but omit the line with @export. Annoyingly, non-exported functions can’t have examples, so you can also delete those. Try to do this yourself before you look at the answer below, but have a look at the help file for round for inspiration.

The title is so descriptive here that I skipped a description.

#' Round with Trailing Zeroes
#'
#' @param x a numeric vector
#' @param digits integer indicating the number of decimal places to be used.
#'
#' @return character string of formatted number

4.3 Importing functions

If you want to use functions from another package without always having to include the package name prefix, you can import those specific functions using roxygen documentation.

#' @importFrom stats t.test sd

You can also import all functions from a package to use without the prefix. I only tend to do this with ggplot2, since it’s really hard to read ggplot code if you have to prefix all of the functions with ggplot2::.

#' @import ggplot2

If you’re going to import functions from a package, you also need to declare it as a dependency of your package:

run in the console
usethis::use_package("ggplot2")

The best place to put roxygen documentation for function or package imports is in a package documentation file. You can set one up with this code:

run in the console
usethis::use_package_doc()

This will make a file in the R directory called demopkg-package.R with the following contents:

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

Edit it to add a title, description, and any imports. You can also get rid of the usethis comments (I’m not sure what those are for).

#' A Demo for Coding Club 2022.
#'
#' The goal of demopkg is to practice making a package.
#'
#' @import ggplot2
#' @importFrom stats t.test sd
#' @keywords internal
"_PACKAGE"

NULL

4.4 Document and Load

Now, you need to run the documentation function to add your function to the package documentation and export it for use.

run in the console
devtools::document()

You should see output like this.

ℹ Updating demopkg documentation
ℹ Loading demopkg
Writing NAMESPACE
Writing apa_t_pair.Rd
Writing demopkg-package.Rd
Writing round0.Rd

Now restart R and make sure that your environment is clear. Run the following code to load your package (Mac: cmd-shift-L, Windows: ctl-shift-L) and view the new Help documentation.

run in the console
devtools::load_all(".")
?round0
?apa_t_pair
?demopkg

4.5 Glossary

term definition
argument A variable that provides input to a function.
console The pane in RStudio where you can type in commands and view output messages.
environment A data structure that contains R objects such as variables and functions
function A named section of code that can be reused.
literal The actual character being typed, not the special meaning it has to code.
markdown A way to specify formatting, such as headers, paragraphs, lists, bolding, and links.
object A word that identifies and stores the value of some data for later use.

4.6 Further Resources

4.7 Further Practice

  1. Add another example to the documentation.

  2. Document any other functions you’ve created.