YARD

What YARD is

YARD is a free documentation generator for Ruby projects that produces API references in HTML or YAML. It reads Ruby, RDoc and Markdown, and is designed to work with RDoc-formatted documentation strings. Its @tag syntax lets authors describe parameters, types, return values, exceptions and deprecation. A built-in renderer handles RDoc and Markdown, while templates let developers customize generated documentation. YARD can also output documented objects as raw data for use in custom formats. For browsing, it serves documentation for a project or installed gem locally, with dynamic search and live reloading. Plugins can extend it for custom Ruby syntax and constructs; the site names integrations for RSpec, DataMapper and Sinatra. YARD is installable with RubyGems and uses the MIT License. The project lists an IRC channel, mailing list and GitHub as contact options. One limit to note: the yri command works with the active project, but not Ruby’s standard library or core libraries.

Who it suits

YARD suits Ruby developers who want to generate API reference documentation from code and documentation strings. Its local server, templates and plugins may help teams that need to browse or customize project documentation.

Limits

The yri command currently works with the active project, but not Ruby’s standard library or core libraries.

Getting started

1. Install YARD with the RubyGems command gem install yard
2. Prepare Ruby, RDoc, or Markdown documentation input
3. Use @tag syntax for parameters, types, returns, exceptions, or deprecation
4. Generate HTML or YAML documentation
5. Serve project or installed-gem documentation locally

Verdict

YARD combines Ruby API documentation generation with local browsing and customization options. Its yri limitation is worth noting if your workflow needs to browse standard or core library documentation.