I’m trying to get better at using docstrings to document my R functions as I write them. A docstring is a block of comments that describe a function, its inputs and output. They are extremely useful tools to help your future self and others understand what your function is doing.
In R a simple template docstring for a function might look like this:
#' Short title for function
#'
#' Longer description of the function
#' @param first An object of class "?". Description of parameter
#' @param second An object of class "?". Description of parameter
#' @return Returns an object of class "?". Description of what the function returns
#' @examples
#' # Add some code illustrating how to use the function
my_new_function <- function(first, second){
# Some code here
return(something)
}
The #'
tells R that this isn’t just any commented line, it is a commented line that forms part of a function’s docstring. The template above can be read by the roxygen R package and used to automatically build a package’s help documentation.
In RStudio use
Ctrl
+alt
+shift
+R
with your cursor inside a function to automatically generate a template docstring! 🎁
We can, and should ⚠️, use the template on any function we write. For example:
#' Calculate mean value
#'
#' Given a numeric vector as input the function will calculate the mean value
#' @param numeric_vector A numeric vector to be used to calculate the mean
#' @return Returns a numeric value representing the mean of the numeric vector provided
#' @examples
#' values <- c(1,2,3,4,5,6,4,3)
#' mean_value <- calculate_mean(numeric_vector)
calculate_mean <- function(numeric_vector){
# Check the vector provided is numeric
if(is.numeric(numeric_vector) == FALSE && length(numeric_vector) > 1){
stop("The input provided was not a numeric vector!")
}
# Get the length of the vector
n <- length(numeric_vector)
# Calculate sum
total <- sum(numeric_vector)
# Calculate mean
mean_value <- total / n
return(mean_value)
}
While roxygen uses the docstring to build a function’s help documentation, the docstring package allows you to use function docstrings on the fly! 🛩
Install (
install.packages("docstring")
) and load the docstring package (library(docstring)
), put your docstring inside your function and run your function code, and then use the?
in the normal way (?my_function_name
) and the help documentation should magically appear!
I still need to go back to previous code and add docstrings but hopefully any new code I write I’ll add them as I go and they’ll be a great help to me and others that use my code in the future!