Documentation with roxygen2
1. Documentation with roxygen2
In this video, we'll create a roxygen2 R function header example, explain the importance of examples in roxygen2 documentation that will become help files, and identify the components of a well-documented R function.2. temp_converter() function definition
Recall our temp_converter function from earlier. Let's work on adding roxygen2 headers to document this function.3. temp_converter() roxygen2 headers for Title and Description
We create a short title for the function to start. Our title is "Convert between Fahrenheit and Celsius temperatures". Remember the need for a new line here separating the title and description. Then, we provide further information about the function in its description. Here, we describe how the temp_converter function works.4. temp_converter() Usage and Arguments
We need to document each argument in the function definition for the Usage and Arguments section. Recall the Usage section is automatically generated. The temp_converter function has three arguments: value which is the temperature number to convert, unit_from as the temperature scale to convert from, and unit_to as the temperature scale to convert to. It is helpful to start with what type of argument it is such as numerical, string, or logical, and then give further details.5. temp_converter() Returns, See Also, and Exports
Next, we will review documenting what is returned from a function, any see also additions, and how to export a function. We give the type of and what is returned from the temp_converter function. Here, assuming no errors, it will be numeric in the unit_to units. While there are plenty of resources on unit conversion, we'll skip it here for See Also since it is an optional component more useful for more specialized analyses that need cited references. Since we want our unitConverter package users to be able to work with temp_converter, we export it.6. temp_converter() Examples
Since our function converts to and from Celsius and Fahrenheit, showing users how to do each is helpful. We do so in the examples section of the roxygen2 header. We start by showing how to convert 25 degrees Celsius to Fahrenheit. Note that the R code does not have any backticks around it here. It is written as it would be in a script file. Next, we show how to convert 100 degrees Fahrenheit into Celsius.7. Importance of Examples in R function documentation
Examples in R function documentation showcase practical usage, helping users see how the function can be applied to solve specific problems. Including examples in R function documentation improves comprehension by clearly demonstrating how the function works, its input requirements, and the expected results. Examples in R function documentation encourage users to explore the function's capabilities, empowering them to modify and customize it for their unique requirements. They also serve as valuable reinforcement, solidifying users' understanding of the concepts and techniques covered.8. Documenting with roxygenize()
We now create the help files from the roxygen2 header with roxygenize and update our NAMESPACE file. Now that we have our roxygen2 header all set up above the temp_converter function definition, we need to let R know to create the dot-Rd file in the man directory and store temp_converter as an exported function. This can be done using the roxygenize function from roxygen2. roxygenize checks that the package can be loaded, updates the NAMESPACE file, and generates the temp_converter-dot-Rd file storing the function documentation.9. Exports go to NAMESPACE file
The NAMESPACE file now includes the export of temp_converter. We now have a well-documented function! This brings joy to our package users.10. Let's practice!
Assess your function documentation skills in the exercises next!Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.