Chapter 11 Documentation

In this section we will describe how to document your code. For more information about code documentation in general, please see the toolbox blog post here. This post describes the differences between the types of documentation, while below we give specific, brief instructions on developer responsibilities for FIMS.

11.1 Writing function reference

Function reference can be written inline in comments above the function in either C++ or R. The tools you can use to generate reference from comments are called Doxygen and Roxygen in C++ and R respectively. Both can include LaTeX syntax to denote equations, and both use @ tags to name components of the function reference

        /**
        * @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 
         */

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

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

You should, at minimum, include the tags @param, @return, and @examples in your function reference if it is an exported function. Functions that are only called internally do not require an @examples tag. Other useful tags include @seealso and @export for Roxygen chunks.

11.2 Writing a vignette

If this is an exported function, a vignette can be a helpful tool to users to know how to use your function. 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")}

11.3 Step by step documentation update process

  1. Write the function reference in either R or C++ as described above

  2. Push to the feature branch.

  3. Ensure that the documentation created by the automated workflow is correct and that any test cases execute successfully before merging into main.