Manuals & Documentation Issues

Missing \value-tags in .Rd-files

Problem

Every .Rd file should have an \value-tag stating what the output of the function is. Even if nothing is returned, the \value-tag is necessary for CRAN.

Solution

Often it is enough to simply add the missing \value-tags. If the function doesn’t return anything, write that as your \value-tag.

Details

CRAN wants a \value-tag for every .Rd-file containing info about the structure of the output (class) and also what the output means.

Adding a short explanation for each function helps users understand effects of the function call. This prevents unexpected outputs and helps to create a better workflow when using the function.

The only exception are .Rd-files for data sets, marked with the \docType{data}-tag. Since these are no functions, no \value-tag is necessary.

Sometimes functions don’t return one specific value but are rather called for their side effects. In that case the \value-tag should state this.

\value{No return value, called for side effects}

When using ‘roxygen’ to render the .Rd-files, an @return-tag must be added in the corresponding .R-file. This will create the \value-tag automatically when rendering.

#' @return What your function returns.

For more details on ‘roxygen2’ check the ‘roxygen2’ section.

---

Repeated Rejections of Issues in Manuals If Using ‘roxygen2’

Problem

The CRAN team rejected your package for issues regarding the manuals a second time, even if you already changed them according to their suggestions.

Solution

Implement your changes in the corresponding .R-files instead of the .Rd-files. Before resubmitting render the .Rd-files again using roxygenize().

Details

If you decide to render your manuals with ‘roxygen2’, the .Rd-files can be render using the function roxygenize(). If changes are implemented directly in the .Rd-file, they will be overwritten during the next render. Similarly, changes in the ‘roxygen2’-section of .R-files will not transfer to the .Rd-files without a re-rendering.

Tip

To avoid this mistake, make sure to always call roxygenize() before submitting your package.

If you want to know more on how to use ‘roxygen2’ to create your manuals, take a look at their website.

Note

When using ‘devtools’, the function devtools::document() acts as a wrapper for roxygenize() and can be used to render the .Rd-files.

---