33 Roxygen2
This is the standard method of documentation used in PEcAn development, it provides inline documentation similar to doxygen.
33.1 Canonical references:
- Must Read: R package development by Hadley Wickham:
- Object Documentation
- Package Metadata
- Roxygen2 Documentation
- Roxygen2 Package Documentation
- GitHub
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.2 Text markup
33.2.2.1 Formatting
\bold{}
\emph{}
italics
33.2.2.2 Links
\url{www.url.com}
or\href{url}{text}
for links\code{\link{thisfn}}
links to function “thisfn” in the same package\code{\link{foo::thatfn}}
links to function “thatfn” in package “foo”\pkg{package_name}
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")