YARD Documentation

YARD is a documentation generation tool for Ruby with the following core capabilities:

1. Hybrid Markup: Built-in support for both RDoc and Markdown.
2. Meta-tag Formatting: Uses @tag syntax for consistent parameter and return type documentation.
3. Extensibility: Supports plugins to handle custom Ruby constructs (e.g., custom class-level definitions like cattr_accessor) and new data structures.
4. Raw Data Output: Can output documented objects as a dumped Namespace for auditing, custom format generation (like YAML), or automated testing.
5. Local Documentation Server: Provides a server for viewing documentation with dynamic searching and live reloading for immediate previews.

The yardoc tool supports a --query argument to include only objects that match a specific Ruby-based data or meta-data query.

Query Syntax Examples

• Tag matching: To document only objects with a specific @api tag value:
  • --query '@api.text == "public"'
  • --query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
  • --query 'has_tag?(:api) && tag(:api).text == "public"'
• Multiple queries: You can use multiple --query flags. They are combined using logical operators like &&:
  • --query '@return' --query '@param' (checks for both)
  • --query '@return && @param'

Note: @tag returns the first tag named tag. Use @@tag to return an array of all tags named tag.

Reference tags apply only to meta-data tags. If a tag's data begins with (see OBJECT), YARD copies the tag data from the specified OBJECT. This is useful for duplicating parameter lists from one method to another.

# @param user [String] the username for the operation
# @param host [String] the host that this user is associated with
# @param time [Time] that this operation took place
def clean(user, host, time = Time.now) end

# Copies all @param tags from #clean
# @param (see #clean)
def activate(user, host, time = Time.now) end

YARD can automatically detect class-level method calls (DSL methods) and treat them as attributes or methods if they are documented. You can use the @attribute tag to explicitly mark a DSL-generated method as an attribute.

class Post
  # @attribute
  # @return [String] the title of the post
  property :title, String
end

As of version 0.6.5, YARD::Registry is thread-local. Creating a new thread implicitly loads a new Registry, allowing for independent parsing and processing of code objects in different threads.

Important: Because the Registry is thread-local, you cannot share a Registry instance across threads. To work with code objects in a different thread, you must either access the thread-local object directly or synchronize your threads to perform processing within the initial registry's thread.

A YARD::CodeObjects::Proxy can represent an object at a specific path that has not yet been created or may never be defined in the current source.

Warning: If you access an attribute on a proxy, it will attempt to resolve to the actual object. If the object exists, the proxy acts as a delegate. If the object does not exist, a warning is raised.

You can check if an object is an unresolvable proxy by checking its type or class:

P(:InvalidObject).type == :proxy  #=> true
P(:InvalidObject).is_a?(Proxy)    #=> true

The parsing component is responsible for the initial data gathering phase. It follows a pipeline where:

1. The Parser reads source files and converts them into statements.
2. Handlers process these statements.
3. Code Objects are created from the processed statements.
4. Tags (metadata) are attached to the code objects.
5. All resulting objects are then added to the YARD::Registry.

The legacy parser is a simpler, non-semantic parser. Instead of a full AST, it groups code into YARD::Parser::Ruby::Legacy::StatementList objects, which consist of YARD::Parser::Ruby::Legacy::Statement objects.

Key differences from the new parser:

• Lexical vs Semantic: Statements are tied to lexical tokens rather than semantic structures. This makes it harder to handle complex Ruby syntax.
• Statement structure: A statement can be a method call, loop, or declaration, and may contain a block.
• Source conversion: To get the source of a statement, you join its tokens using #to_s.
• Usage: Because it lacks deep semantic understanding, users often need to rely on string manipulation or regular expressions when working with legacy parsed data.

You can add YARD-style metadata to the top of extra files using # @tag comments. This allows you to override auto-detection for markup, encoding, or titles.

To prevent these tags from appearing in rendered markdown on platforms like GitHub, wrap the metadata section in an HTML comment.

Supported tags:

• @markup: Specifies the format (e.g., markdown, textile, rdoc, ruby, text, html, or none).
• @encoding: Specifies a non-standard encoding (useful for localized files).
• @title: Specifies a descriptive title for the document (overriding the filename).

<!--
# @markup markdown
# @title The Best Library in the World!
# @author The Author Name
-->

This is the best library you will ever meet. Lipsum ...

Extra files like README.md or CHANGELOG.md can include metadata tags at the top of the file. These tags must be inside a # comment line with no preceding whitespace.

Reserved tags:

• @title: Sets the document title used in menus and indexes.
• @markup: Sets the markup format (e.g., markdown, asciidoc, rdoc).

# @title The Best Project Ever!
# @markup rdoc
# @author Foo Bar

= This Project Rules

== Contents
...