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("roxygen2"). 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

1. 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).
2. 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

1. We generate the documentation files using roxygen2::roxygenise() or devtools::document() (default keyboard shortcut Ctrl+Shift+D)
2. Re-installing the package (default keyboard shortcut Ctrl+Shift+B)
3. 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 <- function(
  path = replaceTilde(rstudioapi::getActiveDocumentContext()[["path"]])
, outputFile = "output.txt"
, suffix = "2>&1") {
  cmd <- makeCmd(path, outputFile = outputFile, suffix = suffix)
  executeCmd(cmd)
  if (!is.null(outputFile) && file.exists(outputFile)) {
    rstudioapi::navigateToFile(outputFile)
  }
}

As we can see by looking at ?runCurrentRscript versus ?mean, our documentation does not quite look up to par with documentation for other functions:

What is missing if we abstract from the richness of the content is the usage of markup commands (tags) for formatting and linking our documentation. Some of the very useful such tags are for example:

• \code{}, \strong{}, \emph{} for style
• \link{}, \href{}, \url{} for linking to other parts of the documentation or external resources
• \enumerate{}, \itemize{}, \tabular{} for using lists and tables
• \eqn{}, \deqn{} for mathematical expressions such as equations etc.

For the full list of options regarding text formatting, linking and more see Writing R Extensions’ Rd format chapter

1. Add a selected tag around a character string

roxyfy <- function(str, tag = NULL, splitLines = TRUE) {
  if (is.null(tag)) {
    return(str)
  }
  if (!isTRUE(splitLines)) {
    return(paste0("\\", tag, "{", str, "}"))
  }
  str <- unlist(strsplit(str, "\n"))
  str <- paste0("\\", tag, "{", str, "}")
  paste(str, collapse = "\n")
}

2. Apply the tag on a selection in an active document in RStudio

We will make the functionality available for multi-selections as well by lapply-ing over the selection elements retrieved from the active document in RStudio.

addRoxytag <- function(tag = NULL) {
  context <- rstudioapi::getActiveDocumentContext()
  lapply(X = context[["selection"]]
       , FUN = function(thisSel, contextid) {
           rstudioapi::modifyRange(location = thisSel[["range"]]
                                 , roxyfy(thisSel[["text"]], tag)
                                 , id = contextid)
         }
       , contextid = context[["id"]]
       )
  return(invisible(NULL))
}

3. Wrappers around addRoxytag to be used as addin for some useful tags

addRoxytagCode <- function() {
  addRoxytag(tag = "code")
}

addRoxytagLink <- function() {
  addRoxytag(tag = "link")
}

addRoxytagEqn <- function() {
  addRoxytag(tag = "eqn")
}

4. Add the addin bindings into addins.dcf and assign keyboard shortcuts

As the final step, we need to add the bindings for our new addins to the inst/rstudio/addins.dcf file and re-install the package.

Name: addRoxytagCode
Description: Adds roxgen tag code to current selections in the active RStudio document
Binding: addRoxytagCode
Interactive: false

Name: addRoxytagLink
Description: Adds roxgen tag link to current selections in the active RStudio document
Binding: addRoxytagLink
Interactive: false

Name: addRoxytagEqn
Description: Adds roxgen tag eqn to current selections in the active RStudio document
Binding: addRoxytagEqn
Interactive: false

assigning keyboard shortcuts to addins

The addins in action