R Documentation Patterns

R Documentation Patterns

Overview

Best practices and patterns for documenting R code, packages, and projects. Covers README files, code comments, function documentation, and project-level documentation.

README Documentation

README Structure

# Package Name

[](https://github.com/user/pkg/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=pkg)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://app.codecov.io/gh/user/pkg?branch=main)

## Overview

Brief description of what the package does (2-3 sentences).

## Installation

```r
# From CRAN
install.packages("pkg")

# Development version from GitHub
# install.packages("pak")
pak::pak("user/pkg")

Usage

library(pkg)

# Basic example
result 
  remove_missing() |>
  transform_variables()

# Analysis ----
# Fit statistical model

model = 4.1)
Imports:
    dplyr (>= 1.0.0),
    ggplot2
Suggests:
    testthat (>= 3.0.0),
    knitr,
    rmarkdown
VignetteBuilder: knitr
Config/testthat/edition: 3

Package-Level Documentation

#' pkgname: A package for doing something useful
#'
#' The pkgname package provides tools for X, Y, and Z.
#'
#' @section Main functions:
#' * [main_function()] - Does the main thing
#' * [helper_function()] - Helps with stuff
#'
#' @section Getting started:
#' See `vignette("pkgname")` for an introduction.
#'
#' @docType package
#' @name pkgname-package
#' @aliases pkgname
"_PACKAGE"

Vignette Structure

Basic Vignette

---
title: "Getting Started with pkgname"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with pkgname}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(pkgname)

Introduction

Brief introduction to the package and its purpose.

Installation

```{r, eval = FALSE} install.packages("pkgname")

## Basic Usage

Walk through a simple example.

```{r}
# Example code
result  B[Input Validation]
    B --> C{Valid?}
    C -->|Yes| D[Data Processing]
    C -->|No| E[Error Message]
    D --> F[Model Fitting]
    F --> G[Results]

Component Descriptions

## Component Overview

### Data Layer
- `read_data()` - Import various data formats
- `validate_data()` - Check data integrity
- `transform_data()` - Prepare for analysis

### Analysis Layer
- `fit_model()` - Core model fitting
- `cross_validate()` - Performance assessment
- `tune_params()` - Hyperparameter optimization

### Output Layer
- `summarize_results()` - Generate summaries
- `export_results()` - Save to files
- `visualize_results()` - Create plots

Dataset Documentation

#' Example Patient Data
#'
#' A simulated dataset containing patient information for
#' demonstrating survival analysis methods.
#'
#' @format A data frame with 100 rows and 5 columns:
#' \describe{
#'   \item{patient_id}{Character. Unique patient identifier.}
#'   \item{age}{Numeric. Patient age in years.}
#'   \item{sex}{Factor with levels `"male"` and `"female"`.}
#'   \item{time}{Numeric. Follow-up time in days.}
#'   \item{status}{Integer. Event indicator (1 = event, 0 = censored).}
#' }
#'
#' @source Simulated data for illustration purposes.
#'
#' @examples
#' data(patients)
#' summary(patients)
"patients"

Documentation Workflow

# Generate documentation
devtools::document()

# Check documentation
devtools::check()

# Preview documentation
?function_name

# Build pkgdown site
pkgdown::build_site()

Best Practices

1. Be concise: Documentation should be clear and to the point
2. Use examples: Include runnable examples for all exported functions
3. Cross-reference: Link to related functions and vignettes
4. Keep updated: Update docs when code changes
5. Use markdown: Enable markdown in roxygen2 for formatting
6. Document edge cases: Explain what happens with unusual inputs
7. Include return values: Always document what the function returns

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: choxos
• Source: choxos/BiostatAgent
• License: MIT

Install and usage instructions live in the source repository linked above.