Introduction
Code documentation is extremely important if you want to share the code with anyone else, future you included. In this second post in the RStudio:addins series we will pay a part of our technical debt from the previous article and document our R functions conveniently using a new addin we will build for this purpose.
The addin we will create in this article will let us create well formatted roxygen documentation easily by using keyboard shortcuts to add useful tags such as \code{} or \link{} around selected text in RStudio.
Contents
Quick intro to documentation with roxygen2
Documenting your first function
Generating and viewing the documentation
Real-life example
Our addins to make documenting a breeze
Add a selected tag around a character string
Apply the tag on a selection in an active document in RStudio
Wrappers around addRoxytag to be used as addin for some useful tags
Add the addin bindings into addins.dcf and assign keyboard shortcuts
The addins in action
What is next - even more automated documentation
TL;DR - Just give me the package
References
Quick intro to documentation with roxygen2
1. Documenting your first function
To help us generate documentation easily we will be using the roxygen2 package. You can install it using install.packages(&quot;roxygen2&quot;). Roxygen2 works with in-code tags and will generate R’s documentation format .Rd files, create a NAMESPACE, and manage the Collate field in DESCRIPTION (not relevant to us at this point) automatically for our package.
Documenting a function works in 2 simple steps:
Documenting a function
Inserting a skeleton - Do this by placing your cursor anywhere in the function you want to document and click Code Tools -__ Insert Roxygen Skeleton (default keyboard shortcut Ctrl+Shift+Alt+R).
Populating the skeleton with relevant information. A few important tags are:
#' @params - describing the arguments of the function
#' @return - describing what the function returns
#' @importFrom package function - in case your function uses a function from a different package Roxygen will automatically add it to the NAMESPACE
#' @export - if case you want the function to be exported (mainly for use by other packages)
#' @examples - showing how to use the function in practice
2. Generating and viewing the documentation
Generating and viewing the documentation
We generate the documentation files using roxygen2::roxygenise() or devtools::document() (default keyboard shortcut Ctrl+Shift+D)
Re-installing the package (default keyboard shortcut Ctrl+Shift+B)
Viewing the documentation for a function using ?functioname e.g. ?mean, or placing cursor on a function name and pressing F1 in RStudio - this will open the Viewer pane with the help for that function
3. A real-life example
Let us now document runCurrentRscript a little bit:
#' runCurrentRscript
#' @description Wrapper around executeCmd with default arguments for easy use as an RStudio addin
#' @param path character(1) string, specifying the path of the file to be used as Rscript argument (ideally a path to an R script)
#' @param outputFile character(1) string, specifying the name of the file, into which the output produced by running the Rscript will be written
#' @param suffix character(1) string, specifying additional suffix to pass to the command
#' @importFrom rstudioapi getActiveDocumentContext
#' @importFrom rstudioapi navigateToFile
#' @seealso executeCmd
#' @return side-effects
runCurrentRscript