1. Help files with R packages
Welcome back! We'll next recognize the components of a function help file and identify exported and non-exported function differences. We'll generate roxygen2 documentation in the following videos and discover R package vignettes.
2. R package structure
We are now focussing on the documentation portion of the R package structure.
3. Help files for functions
Function help files like this one for the use_package function provide an inclusive overview of a function with title and description,
4. Help files for functions
enumerating all the parameters it accepts while clarifying the purpose and application of each. When functions take similar arguments they can be included together as is done here with the use_dev_package function.
5. Help files for functions
Help files also furnish details about the function's output, examples, and more. The order of these components is set by CRAN.
6. roxygen2 headers for Title and Description
We'll need the roxygen2 package to generate help files. We'll see this in the next video. For now, let's look at the components.
A roxygen2 header is created by the package author above the function definition. Every line of the roxygen2 header starts with a hash followed by a single quote. As an example here, the title of the use_package function is given as a short phrase summarizing the function purpose.
This must be followed by a new line and the function description that provides information about the function's goals.
7. Usage and roxygen2 header for Arguments
The Usage portion of the help file is automatically generated from the function definition. With the focus on showing how the help file is created, we don't show the usage portion directly here.
Recall use_package takes three arguments with two of them including default values for type and min_version.
The Arguments portion is created in the next roxygen2 block. Here the special tag of @param is included with the name of the function parameter and then a description of its purpose.
min_version is described as the minimum version of the package to be added optionally.
Here we also see the remote argument used in use_dev_package.
8. roxygen2 headers for Returns and See Also
The use_package function doesn't return anything. It just performs a task. We need to let our users know what the function returns for most functions. For example, we can notify users of a converter function output with @returns.
An optional place to add additional references is with the @seealso tag. In this example, the usethis package creator added a textbook for further reading about package dependencies.
9. Exported versus non-exported functions
Before proceeding with roxygen2, we need to discuss exporting a function versus not.
An exported function is loaded when the package is loaded. This is why we call use_package directly after library is called. They are documented in the package's help files, allowing end users to understand their purpose, usage, and arguments. Exported functions provide the core functionality of the package.
A non-exported function must be called with the three colons we saw previously. They may be documented, but are designed to perform extra tasks. Non-exported functions help exported functions execution.
10. How to export a function
Currently all of the functions in the unitConverter package are non-exported.
Functions are not exported by default. That's the reason why we needed to use three colons earlier when calling a function after dumping it into an R file.
To export a package function like use_package we add a line to its roxygen2 header, that is only the @export tag.
11. Examples
Including usage examples in the package documentation is important. Use the @examples tag to provide practical examples for users to adapt as needed. The example R code can be wrapped in backslash-don't run, so it can be copied by the user to execute. We've now seen how the help file components are created using a roxygen2 header.
12. Let's practice!
Let's practice!