Introduction to docstring

Dason Kurkiewicz

2017-03-24

The docstring package is a package for R that provides the ability to display something analagous to Python’s docstrings within R. By allowing the user to document their functions as comments at the beginning of their function without requiring putting the function into a package we allow more users to easily provide documentation for their functions. The documentation can be viewed using an accessor function but displays just like any other R help files.

The user will need to be familiar with roxygen style comments (via the roxygen2 package) to fully utilize the package.

In this vignette we will walk through a few examples to give you an introduction to what the package does and some simple examples of how to format your documentation to be used with docstring.

At it’s most basic documentation can just be a sentence or two describing what a function does.

square <- function(x){
    #' Computes the square of the input
    return(x^2)
}

The comment at the beginning serves as our documentation of what the function does. If we wanted to view the documentation we could print the entire function in which case we would be able to see the documentation in the source.

square
## function(x){
##     #' Computes the square of the input
##     return(x^2)
## }

However for longer functions that can be incovenient. The built in help system in R is the ideal way to view help for functions. By default we can’t use the help system to view the documentation we wrote in the square function.

?square
## No documentation for 'square' in specified packages and libraries:
## you could try '??square'

However, using the docstring package will allow us to do just that for functions that have a corresponding docstring. For functions that don’t have a docstring it will fall back to the ‘typical’ functionality of ?. Note that this vignette has been configured to display the help documentation as output in the console.

library(docstring)
## 
## Attaching package: 'docstring'
## The following object is masked from 'package:utils':
## 
##     ?
?square # Below is the generated help file:
Title not detected

Description:

     Computes the square of the input

Usage:

     square(x)
      

More complex docstring

When the docstring is just a single chunk of text you’ll notice that the generated help file puts the text in the “Description” section and has “Title Not Detected”. This is a convenience feature but the documentation comments can (and should in most cases) follow the standards set by the roxygen2 package. So this means that the first chunk of comments before a blank line is taken to be the title, the second chunk is taken to be the Description section, and the rest goes in the “Details” section. You can have finer control over these things by using keywords but let’s look at an example in action

test <- function(){
    #' This is my title line
    #'
    #' All of this text goes
    #' in the Description section
    #'
    #' This part goes in the Details!
    return()
}

?test
This is my title line

Description:

     All of this text goes in the Description section

Usage:

     test()
     
Details:

     This part goes in the Details!
 

You’ll notice that the “usage” portion gets generated automatically.

Using keywords

The standard set in roxygen2 allows the use of keywords to specify different sections and the corresponding documentation. For example if you want to provide documentation explaining what one of the input parameters means you could include a line that starts with @param parameter_name which will create an Arguments section and place the documentation about the input parameters there.

square <- function(x){
    #' Squares a number
    #'
    #' Provides the square of the input
    #' @param x The value to be squared
    return(x^2)
}

?square
Squares a number

Description:

     Provides the square of the input

Usage:

     square(x)
     
Arguments:

       x: The value to be squared
 

You can see that the “Arguments” section gets automatically generated using the documentation you wrote on the line that started with @param. When using docstring it isn’t expected that you are in the process of building a package. If you were you would most likely put your documentation above the function as that is the style that is typically required in package building via roxygen2. Due to that I’ll only describe a subset of the keywords that are available to the user but if you are interested in more on how elaborate you can make your documentation I would suggest reading the Generating Rd files vignette for the roxygen2 package.

Some of the other useful keywords that I can forsee users using with docstring are:

So now to illustrate all of this I will present an example function that uses all of these keywords. The function is pointless and the documentation is gibberish but it should allow you to see how to format the docstring using the keywords and what the corresponding help file will look like.

mypaste <- function(x, y = "!"){
  #' Paste two items
  #' 
  #' @description This function pastes two items
  #' together.  
  #'
  #' By using the description tag you'll notice that I
  #' can have multiple paragraphs in the description section
  #' 
  #' @param x character. The first item to paste
  #' @param y character. The second item to paste Defaults to "!" but
  #' "?" would be pretty great too
  #' @usage mypaste(x, y)
  #' @return The inputs pasted together as a character string.
  #' @details The inputs can be anything that can be input into
  #' the paste function.
  #' @note And here is a note. Isn't it nice?
  #' @section I Must Warn You:
  #' The reference provided is a good read.
  #' \subsection{Other warning}{
  #'   It is completely irrelevant to this function though.
  #' }
  #' 
  #' @references Tufte, E. R. (2001). The visual display of 
  #' quantitative information. Cheshire, Conn: Graphics Press.
  #' @examples
  #' mypaste(1, 3)
  #' mypaste("hey", "you")
  #' mypaste("single param")
  #' @export
  #' @importFrom base paste

  return(paste(x, y))
}

?mypaste
Paste two items

Description:

     This function pastes two items together.

     By using the description tag you'll notice that I can have
     multiple paragraphs in the description section

Usage:

     mypaste(x, y)
     
Arguments:

       x: character. The first item to paste

       y: character. The second item to paste Defaults to "!" but "?"
          would be pretty great too

Details:

     The inputs can be anything that can be input into the paste
     function.

Value:

     The inputs pasted together as a character string.

I Must Warn You:

     The reference provided is a good read.

  Other warning:

       It is completely irrelevant to this function though.


Note:

     And here is a note. Isn't it nice?

References:

     Tufte, E. R. (2001). The visual display of quantitative
     information. Cheshire, Conn: Graphics Press.

Examples:

     mypaste(1, 3)
     mypaste("hey", "you")
     mypaste("single param")