33 Roxygen2

This is the standard method of documentation used in PEcAn development, it provides inline documentation similar to doxygen.

33.1 Canonical references:

33.2 Basic Roxygen2 instructions:

Section headers link to “Writing R extensions” which provides in-depth documentation. This is provided as an overview and quick reference.

33.2.1 Tags

  • tags are preceeded by ##'
  • tags required by R: ** title tag is required, along with actual title ** param one for each parameter, should be defined ** return must state what function returns (or nothing, if something occurs as a side effect
  • tags strongly suggested for most functions: ** author ** examples can be similar to test cases.
  • optional tags: ** export required if function is used by another package ** import can import a required function from another package (if package is not loaded or other function is not exported) ** seealso suggests related functions. These can be linked using \code{link{}}

33.2.2 Text markup

33.2.2.1 Formatting

  • \bold{}
  • \emph{} italics

33.2.2.3 Math

  • \eqn{a+b=c} uses LaTex to format an inline equation
  • \deqn{a+b=c} uses LaTex to format displayed equation
  • \deqn{latex}{ascii} and \eqn{latex}{ascii} can be used to provide different versions in latex and ascii.

33.2.2.4 Lists

\enumerate{
\item A database consists of one or more records, each with one or
more named fields.
\item Regular lines start with a non-whitespace character.
\item Records are separated by one or more empty lines.
}
\itemize and \enumerate commands may be nested.

33.2.2.5 “Tables”:http://cran.r-project.org/doc/manuals/R-exts.html#Lists-and-tables

\tabular{rlll}{
[,1] \tab Ozone \tab numeric \tab Ozone (ppb)\cr
[,2] \tab Solar.R \tab numeric \tab Solar R (lang)\cr
[,3] \tab Wind \tab numeric \tab Wind (mph)\cr
[,4] \tab Temp \tab numeric \tab Temperature (degrees F)\cr
[,5] \tab Month \tab numeric \tab Month (1--12)\cr
[,6] \tab Day \tab numeric \tab Day of month (1--31)
}

33.3 Example

Here is an example documented function, myfun

##' My function adds three numbers
##'
##' A great function for demonstrating Roxygen documentation
##' @param a numeric
##' @param b numeric
##' @param c numeric
##' @return d, numeric sum of a + b + c
##' @export
##' @author David LeBauer
##' @examples
##' myfun(1,2,3)
##' \dontrun{myfun(NULL)}
myfun <- function(a, b, c){
  d <- a + b + c
  return(d)
}

In emacs, with the cursor inside the function, the keybinding C-x O will generate an outline or update the Roxygen2 documentation.

33.4 Updating documentation

  • After adding documentation run the following command (replacing common with the name of the folder you want to update): ** In R using devtools to call roxygenize:
require(devtools)
document("common")