Documentation with roxygen2

Developing R Packages

Jasmin Ludolf

Content Developer

temp_converter() function definition

temp_converter <- function(value, unit_from = "Celsius", unit_to = "Fahrenheit") {
  if (unit_from == "Celsius" && unit_to == "Fahrenheit") {
    return(value * 9/5 + 32)
  } else if (unit_from == "Fahrenheit" && unit_to == "Celsius") {
    return((value - 32) * 5/9)
  } else if (unit_from == unit_to) {
    warning("unit_from and unit_to are the same, value returned.")
    return(value)
  } else {
    stop("Invalid unit_from or unit_to. Only 'Celsius' and 'Fahrenheit' 
         are accepted.")
  }
}

temp_converter() roxygen2 headers for Title and Description

#' Convert between Fahrenheit and Celsius temperatures
#'

#' `temp_converter()` performs the conversion based on the specified `unit_from` 
#' and `unit_to` values. If the conversion is not possible due to invalid units or 
#' if `unit_from` and `unit_to` are the same, appropriate warnings or errors 
#' are raised.

temp_converter() Usage and Arguments

temp_converter <- function(value, unit_from = "Celsius", unit_to = "Fahrenheit")

#' @param value A numerical value of the temperature to be converted.
#' @param unit_from A character string of the temperature unit to convert from 
#'   (default is "Celsius").
#' @param unit_to A character string of the temperature unit to convert to 
#'   (default is "Fahrenheit").

temp_converter() Returns, See Also, and Exports

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

See Also skipped for this function

#' @export

temp_converter() Examples

#' @examples
#' # Convert 25 degrees Celsius to Fahrenheit 
#' temp_converter(25, unit_from = "Celsius", unit_to = "Fahrenheit")

#' # Convert 100 degrees Fahrenheit to Celsius 
#' temp_converter(100, unit_from = "Fahrenheit", unit_to = "Celsius")

Importance of Examples in R function documentation

Practical usage

Improves comprehension

Encourages exploration

Reinforces understanding

A person in front of a laptop pictured twice, first they are confused with a question mark, and then they are pictured with a light bulb, no longer confused

Documenting with roxygenize()

Update the NAMESPACE file

library(roxygen2)
roxygenize()

roxygenize() output

Exports go to NAMESPACE file

`# Generated by roxygen2: do not edit 
'# by hand

export(temp_converter)

Happy package user

Let's practice!

Developing R Packages