How should I document custom functions?

[cenuno]

When documenting R functions that I write, what is the best way to document them?

[cenuno]

Write documentation for you 6-months from now

The best documentation for custom R functions centers on providing enough context behind the necessity of the function and what problem it solves. This context is key as it will often be necessary to understand what your function currently does when you or someone on your team is curious about else it can do.

Introducing the docstring package

One way we all interact with functions is via the ?<FUNCTION> command within the R console. Whenever we come across something we don't know, the ?<FUNCTION> command opens up the Help tab within RStudio which is home to a treasure chest of documentation.

Once run, ?<FUNCTION> displays the documentation related to that specific <FUNCTION>. It's a tremendous tool that aids in learning what exactly as function does!

Applying the docstring package to your custom functions

When you write your R function documentation using the docstring package, you're tagging commented out lines of code with special keywords. These keywords are then parsed, converted into HTML, and displayed in the Help tab within RStudio.

Again, this is helpful because you save the user time by allowing them to view documentation related to your custom function without making them read the source code.

Example

Below you will notice that the filter_by_description() function is a user-defined function that has two different comment styles: # and #'. We're all familiar with the former as it is what we use to write comments; the latter is what is used when using the docstring specific keywords (i.e. #' @title).

The keywords flow in such a way that you end up writing enough context to help your future self understand what you were doing.

# load necessary packages ----
library(docstring)

# searches variable descriptions for a specific string and return matches ----
filter_by_description = function(description){
  #' @title Searches variable descriptions for a specific string
  #' @description searches variable descriptions for a specific string and return matches
  #' @param description (string): phrase or word wrapped in quotation marks
  #' @return dataframe: all metadata records that match the description

 # removing logic that does this since it is part of Lab02
  return NULL
}

Once filter_by_description is in the Global Environment, you can access its documentation via ?filter_by_description call. This will open the documentation in the Help tab within RStudio.

Be sure to checkout the docstring package tutorial so that you can understand this powerful tool with more context!