name: r-docstrings description: > document r code with roxygen2 comments so external tools can read the embedded api documentation. use when the request is to add, normalize, migrate, review, or explain r source documentation, inline api help, or machine-readable comments.

R Docstrings

Use this skill to add or normalize roxygen2 comments in R code so external tools can discover API intent without reverse-engineering the implementation.

Intent Router

Quick Start

1. Inspect the repository for an existing documentation convention.
2. Preserve an established machine-readable style when it already works with external tooling.
3. Otherwise standardize on roxygen2 comments for the requested R surface.
4. Document public and externally consumed symbols before private helpers.
5. Keep names, parameters, return semantics, and examples aligned with the real code.

Workflow

• identify the externally consumed surface before adding comments or rewriting existing documentation
• add documentation directly adjacent to the declaration or symbol that external tools inspect
• prefer concise summaries first, then parameters, returns, exceptions, examples, or side effects when the format supports them
• mention or preserve the extraction path used by the surrounding toolchain
• keep migrations incremental when mixed styles already exist in a large file or module

Output Pattern

• state the convention being applied and why it matches the surrounding toolchain
• show declaration-adjacent documentation blocks rather than detached prose
• mention extraction or verification commands when they help confirm the result
• call out any symbols intentionally left undocumented because they are private or out of scope

Canonical Pattern

#' Add two integers
#'
#' @param a Left operand.
#' @param b Right operand.
#' @return Sum of the operands.
add <- function(a, b) {
  a + b
}

Extraction Path

roxygen2::roxygenise()
devtools::document()

Common Requests

Add or normalize R source documentation for this public API without changing behavior.

Review this R file for missing or misleading machine-readable documentation that external tools depend on.

Verification and Migration Checks

• verify the generated docs with the extraction path, metadata query, or generator named in references/docstrings.md
• compare parameter names, return values, exceptions, ownership notes, and examples against the real declaration after editing
• migrate one contiguous public surface at a time when a file mixes styles
• preserve an existing machine-readable convention when external tooling already depends on it, and state that choice explicitly

Recovery Cues

• if the repository already standardizes on another adjacent format, keep that format instead of forcing a conversion
• if a declaration is still unstable or private, document only the parts external tools or callers actually consume
• if behavior is unclear, reduce the prose to verified facts and mark open questions instead of inventing guarantees

Safety Notes

• do not invent behavior, preconditions, side effects, performance guarantees, or error modes that the code does not actually implement
• do not document private members unless the request, generator, or house style requires them
• do not mix competing documentation styles in the same file without a clear migration reason
• do not let examples drift away from the real API surface