Introduction to docstring

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:

• @return description to describe the output that a function creates.
• @title, @description, @details are available if you want to be more explicit in the sections. This also allows you to have a description section longer than one paragraph if you explicitly use the description keyword.
• @note Creates a note section
• @section SectionTitle: You can create your own sections using the section keyword. Following @section must be the section title in sentence case and must be finished with a colon. Subsections do not have their own keyword but can be added using the Rd \subsection{} command.
• @usage If you want to have more control over the usage section you can either overwrite the generated usage or add to it by using this keyword
• @references If you want to add references to your documentation. This is important (and appreciated) especially when you are writing a function that implements an algorithm in a journal article. Having a reference to the source is vital in those situations.
• @examples which will create an examples section in the documentation. Using docstring there isn’t a nice way to run the examples like you can using the example() function but they will still show up in the documentation which is sometimes the most important part. Users can still copy/paste if they desire.
• @export, @import, @importFrom These are keywords that are highly useful for and only really make sense in the context of package creation. docstring isn’t meant to be used for full packages so you wouldn’t expect me to comment on these keywords. However, docstring is a nice tool to use in the time before package creation so it is understandable that if somebody thought their code will turn into a package someday that they might want to get a jump start on all of the documentation (including the namespace directives). There is nothing stopping a user from using these keywords. They won’t do anything when used with docstring though.

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")