Chapter 9 Documentation Template

Below, are specific, brief instructions on developer responsibilities for FIMS regarding documentation. For more information about code documentation in general, please see the toolbox blog post on code documentation.

9.1 Writing function reference

Function reference can be written inline in comments above the function in either C++ or R. Doxygen and Roxygen in C++ and R, respectively, are used to render the documentation. Both can include LaTeX syntax to denote equations and both use @ tags to name components of the function reference. Below is an example from C++ code.

        /**
        * @brief This function calculates the von Bertalanffy growth curve.
         * \f$
         *
         * length\_at\_age = lmin + (lmax - lmin)*\frac{(1.0 -
                    c^ {(age - a\_min)}))}{(1.0  - c^{(a\_max - a\_min)})}
         *
         * \f$
         *
         * @param age
         * @param sex
         * @return length\_at\_age
         */

which can be be rendered using via the following lines in the Command Prompt:

cmake -S. -B build -G Ninja
cmake --build build

The only difference between the syntax for R and C++ code is how comments are denoted in the language. Below is an example from R code.

#' This function calculates the von Bertalanffy growth curve.
#'
#' @param age
#' @param sex
#' @return length_at_age

which can be rendered in R with devtools::document().

You should, at minimum, include the tags @param, @return, and @examples in your documentation for all exported functions. Functions that are only called internally do not require an @examples tag. See the r-lib for all available tags and best practices.

9.2 Writing a vignette

Vignettes can be a helpful tool to let users to know how to use functions. If you include a vignette for your function, you can link to it in the Roxygen documentation with the following code.

#' \code{vignette("help", package = "mypkg")}