09-documentation-templates.Rmd

# 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](https://noaa-fisheries-integrated-toolbox.github.io/resources/developer%20resources/code-documentation/).

## 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:

```bash
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](https://roxygen2.r-lib.org/) for all available tags and best practices.

## 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")}
```