YARD: @tag annotations and a live server for Ruby documentation

@param and @return carry type information that plain comments cannot

YARD takes the convention of documenting Ruby methods in source comments and adds a structured annotation layer on top of it. Each @tag entry in a YARD-processed comment gives a parameter, return value, or exception a formal record, with type information in square brackets. Plain prose comments describe what a method does; @param tags declare what types a caller may pass.

A `reverse` method in the README demonstrates what the tags look like in practice:

# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
  contents = contents.read if contents.respond_to? :read
  contents.reverse
end

Here, @param declares that `contents` accepts either a String or any object responding to `#read`, which is Ruby's duck typing idiom rather than a class hierarchy requirement. YARD's documentation then calls this tag "more powerful than the textual description, which says it should be an IO object." That sentence mischaracterizes its own example: the prose comment at the top of the same method reads "a String or IO object," meaning String was already named there. What the @param tag actually adds is precision about duck typing, expressed as `#read` rather than a concrete class name. A reader skimming the README for that explanation could miss the distinction.

Returning a String is recorded by @return on the next line. Together, these 2 tags give a caller precise type information without requiring them to read the method body. A full list of supported tags lives in docs/Tags.md inside the repository.

Installing YARD and generating the first documentation output

YARD is distributed as a Ruby gem. One command adds it to a system or a project:

gem install yard

From a source checkout, the README gives `rake install` as an alternative. After installation, the `yard` binary is available. Running it without arguments shows what subcommands exist:

yard --help

Plugins can add new subcommands to the `yard` executable, so the list may be longer in a project that uses YARD plugins. The primary subcommand is `yard doc`, which has a shortcut alias named `yardoc`. Running either from a Ruby project root reads source files and generates HTML documentation. Flags that apply to every documentation build can be saved in a `.yardopts` file at the project root, so they do not need to be passed on each invocation.

YARD's own repository ships with 3 `.yardopts` variants at its root: `.yardopts`, `.yardopts_guide`, and `.yardopts_i18n`. Having a dedicated `.yardopts_i18n` shows that YARD supports a multi-language documentation workflow, though the README provides no walkthrough for it. For that, the documentation at yardoc.org is where to look.

The built-in renderer covers basic RDoc and Markdown without gems, but not GitHub-Flavoured fenced blocks

YARD ships with a renderer that handles both RDoc and Markdown formatting without installing any extra gems. Switching between them is a flag to `yard doc`: pass `-m markdown` for Markdown mode, or `-m rdoc` for RDoc. Either value can be stored in `.yardopts` to avoid repeating it.

For GitHub-Flavoured Markdown specifically, the built-in renderer is not enough. Fenced code blocks using triple backticks, tables, and specific Markdown extensions require an external provider gem. The README names 3 options: `redcarpet`, `commonmarker`, and `kramdown`. Once installed, the provider is selected with `-M PROVIDER` alongside `-m markdown`:

yard doc -m markdown -M redcarpet

A project whose method comments contain triple-backtick fences will see those blocks in the generated HTML only if one of those 3 gems is installed and selected. Testing the rendered output with a sample method comment is the practical way to verify the combination works. YARD's README gives the provider options but not a complete specification of what the built-in renderer handles on its own.

Custom Ruby constructs require writing a YARD handler, not adding more tags

Standard documentation tools document classes and methods as Ruby defines them. YARD extends this by letting developers register handlers for constructs that generate code dynamically at runtime. YARD's README presents its capabilities as 5 numbered features, and custom construct extensibility is feature 3.

The README gives `cattr_accessor :publisher` as the example, a macro common in Rails-style frameworks that creates a class attribute without a standard Ruby method definition. Without a handler, a documentation tool sees a method call and produces nothing for the generated attribute. With a handler registered in YARD, the tool creates the appropriate attribute documentation whenever it encounters that pattern.

Writing a handler is not a configuration step or a tag addition. It requires Ruby code that teaches YARD the semantics of a specific macro: what names it creates, what types it produces, and how its arguments map to the generated items. YARD is designed to handle "custom class level definitions" and to support "new programming languages, new data structures and even where/how data is stored," as the README puts it.

A project using standard Ruby class and method syntax will never need to write a handler. A project built on a framework that defines attributes, associations, or callbacks through macros will find that YARD's documentation coverage depends on whether handler code exists for those patterns, either from YARD's plugin ecosystem or written specifically for the project.

The namespace dump separates source parsing from output generation

Most documentation pipelines parse source and write HTML in one pass. YARD separates those 2 phases. After parsing, it can write the parsed object namespace as a dump to disk. That dump can be loaded later to regenerate output without re-reading source files, or fed to tools that need YARD's parsed structure but not YARD's HTML output.

YAML is named in the README as 1 possible output target, and feeding the raw data into a database or using it to auto-generate test cases are given as further possibilities. These are use cases the dump format enables, not built-in features with their own documented commands. For a team running a standard `yard doc` pipeline, the 2-phase architecture operates in the background without any special configuration.

This matters most for tooling authors. A custom site generator building on YARD's parsing, or a code analysis tool that wants method signatures and return types in structured form, can build against this layer without coupling to YARD's HTML templates. YARD calls this output the "dumped Namespace" that can be reloaded for later generation or code auditing.

The YARD server adds dynamic search and live reload to what gem server already offers

Ruby's built-in `gem server` command serves installed gem documentation, but it is static: refreshing the page shows the last generated output with no way to search across gems. YARD's server extends that baseline with 2 additions: dynamic searching across all indexed gems and the current project's documentation, and live reloading while writing documentation.

With live reload running, saving a source file causes YARD to regenerate documentation for that file. Refreshing the browser shows the updated output without running `yard doc` again. According to the README, live reload makes writing documentation "a much faster process."

Server configuration details are not in the README. Port numbers, how to start the server, and any access controls are documented at yardoc.org. Version 0.9.45 was released on 2026-07-14 and v0.9.44 on 2026-05-25; the last push to the repository was on 2026-08-25.

When plain RDoc remains the simpler path and YARD adds more than it returns

YARD says its tags are able to "sit side by side RDoc formatted documentation," so adopting it does not require rewriting every existing comment. However, it adds a dependency, a configuration file, and a tagging convention that every contributor to the project needs to learn and follow.

For projects that already maintain consistent prose-style RDoc comments and have no public API with complex type signatures, that cost sits on the wrong side of the trade-off. RDoc is installed with Ruby itself, requires no extra gem, and produces usable documentation for methods with clear names. Adding @param and @return tags retrospectively across a large codebase is a sizable task. YARD makes no claim about inferring or filling in missing annotations: it documents what the developer annotates, nothing more.

On the extensibility side, YARD can be configured to support additional programming languages and data structures, but for a standard Ruby project it does not displace RDoc's parser. Two tools co-exist in the same codebase, and the decision to adopt YARD is mostly a question of whether machine-readable type annotations justify the ongoing maintenance they require.

Editorial conclusion

Use YARD when your Ruby library has a public API where method signatures do not convey the accepted types, or when your project uses class-level macros that need consistent documentation. Skip it when your team already maintains RDoc comments and has no need for @tag type annotations, because retrofitting tags to an existing codebase costs real time. Before adopting, check whether DSL macros in the codebase have existing YARD handlers, since undocumented macros produce no output. Test Markdown comments with the built-in renderer: fenced code blocks need redcarpet, commonmarker or kramdown before yard doc handles them.

Frequently asked questions

Official sources

1. License: MIT
2. lsegal/yard on GitHub
3. Project website
4. README
5. Releases