Function Documentation — Document functions with comments/roxygen-style basics (intro)

The practice of documenting code is nearly as old as programming itself, yet the discipline of function documentation — structured annotations that describe a function's purpose, parameters, and return values — evolved considerably over the decades. Early programmers used inline comments sparingly, relying instead on external manuals and printed reference cards to explain what their code did. As software systems grew in complexity throughout the 1970s and 1980s, the gap between what code did and what developers understood about it became a serious engineering problem. The idea that documentation should live alongside the source code, rather than in separate binders, gradually gained traction across multiple language ecosystems.

The central question this lesson addresses is deceptively simple: how do you write R functions that explain themselves? Without clear documentation, even well-written code becomes opaque within weeks — to collaborators and to your future self. Understanding both basic comment conventions and the roxygen2 annotation system equips you to produce code that is not only functional but also comprehensible, reusable, and suitable for professional-grade package development.

Effective function documentation in R rests on several foundational principles that apply whether you are writing a quick analysis script or building a CRAN package. These principles guide you in choosing what to document, where to place annotations, and how to structure them so that both human readers and automated tools can parse your intent. Mastering these ideas early will save you significant time as your projects scale from single-file scripts to multi-function packages.

The diagram below illustrates the structure of a fully documented R function using roxygen2-style comments. Each colored region corresponds to a specific documentation element: the title, the description, parameter tags, the return tag, examples, and finally the function body itself. Notice how the roxygen2 block (lines beginning with #') immediately precedes the function assignment, maintaining the proximity principle.

The critical detail to notice is the distinction between the #' (hash-apostrophe) prefix used by roxygen2 and the standard # prefix used for regular R comments. Regular comments are completely ignored by the documentation generation pipeline; they serve only as inline notes for developers reading the source. Roxygen2 comments, on the other hand, are parsed, validated, and converted into the .Rd files that R's help system displays when you call ?function_name.

Understanding the roxygen2 pipeline helps clarify why structured tags matter. When you run devtools::document() or roxygen2::roxygenise(), the roxygen2 package scans every .R file in your R/ directory, extracts all blocks prefixed with #', parses the tags within them, and generates the corresponding .Rd documentation files in the man/ directory. This process is deterministic: each roxygen2 block maps to exactly one help page, and the tags within the block dictate the sections of that page.

The pipeline diagram makes an important architectural point: you never edit .Rd files by hand when using roxygen2. The man/ directory is entirely generated output. This means your single source of truth for both code and documentation is the .R file itself — a significant improvement over the legacy workflow where you had to maintain two separate files and manually keep them synchronized.

While roxygen2 supports dozens of tags for advanced use cases — controlling namespaces, documenting S4 classes, specifying package-level metadata — this introduction focuses on the six tags you will use most frequently. Mastery of these six covers approximately 90% of day-to-day documentation needs in R programming.

Writing Effective @param Descriptions

A high-quality @param description answers three questions: What type is it? (numeric vector, character string, logical, data frame), What does it represent? (a temperature in Celsius, a column name), and What constraints apply? (must be positive, length one, one of a specific set of values). Omitting any of these forces the user to read the function body to understand usage — the exact situation documentation is meant to prevent.

• Good: @param alpha Numeric scalar in (0, 1). Significance level for the test. Default is 0.05.
• Poor: @param alpha The alpha value.
• Good: @param method Character string. One of "pearson", "kendall", or "spearman".
• Poor: @param method The method to use.

Let us walk through documenting a function that computes a z-score normalization on a numeric vector. We will build the roxygen2 block tag by tag, explaining the reasoning behind each decision.

Both plain R comments and roxygen2 annotations serve legitimate documentation purposes, but they target different audiences and workflows. Understanding when to use each — and their respective trade-offs — prevents over-engineering scripts while ensuring packages meet community standards. The table below provides a direct comparison across several dimensions relevant to professional R development.

The introductory roxygen2 tags covered in this lesson form the foundation for a much richer documentation ecosystem. As your R packages grow in complexity, you will encounter advanced features that build directly on the concepts you have learned here. Understanding this trajectory helps you appreciate why getting the basics right matters — the advanced features extend the tag system rather than replacing it.

Beyond roxygen2, the modern R documentation landscape includes tools like pkgdown (which converts your roxygen2-generated help pages into a full website), testthat (where examples evolve into formal unit tests), and R Markdown / Quarto for literate programming that blends narrative, code, and output. All of these tools build on or complement the roxygen2 foundation, so investing in clean roxygen2 habits now pays compounding dividends as your projects mature.