Yard Documentation

YARD Documentation

General YARD documentation rules and workflow for all Ruby source code.

Contents

• Contents
• How to use this skill
• Related skills
• Reference files
• Precedence
• Workflow
• Named length limits
• Step 1: Identify What Needs Documentation
• Step 2: Write Documentation
  • Standard template (no @overload)
  • Overload template
  • Overload decision matrix
  • Documenting anonymous splats with @overload
  • Documenting other elements
• Step 3: Verify Documentation
  • Line and summary length checks
• Documentation Standards
  • Formatting Rules
    • Doc comment placement
    • Blank lines around tags
    • Never use raw blank lines inside a doc comment block
    • Short descriptions
    • Line and summary length
    • @return must always include a type
    • No shell calls in @example blocks
    • Blank lines within @example blocks
    • @example titles are required
    • Cross-reference links only resolve to objects included in generated docs
    • Inline code formatting
    • Escaping opening braces in descriptions
    • Cross-reference links
    • Type specifier conventions
    • Array<...> (collection) vs Array(...) (tuple)
    • @api private vs @private
    • Class and module @api visibility (Required)
    • @since tags are not used
    • @todo tags are not used
    • @abstract
  • Method Rules
    • Short description
    • Standard tags
    • @example on non-private methods
    • Yield tags
    • @overload for distinct signatures
    • @overload for anonymous splats
    • @note for callouts (Optional)
    • @deprecated on deprecated methods
    • @api on methods (Optional)
• Command Reference

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the source files that need YARD updates. Use it when adding new APIs, fixing doc warnings, or improving existing YARD quality and examples.

Work top to bottom: follow the three-step Workflow, reaching into the Documentation Standards reference below as you write, and into element-rules.md when documenting a class, module, constant, attribute, dynamically defined method, or value object.

Related skills

• Command YARD Documentation — command-specific rules for writing and reviewing YARD docs on Git::Commands::Base subclasses

Reference files

Situational rules live in a sibling file, loaded only when the element type calls for it:

• element-rules.md — per-element requirements for classes, modules, constants, attributes, dynamically defined methods, and value objects (Data.define / Struct.new). Read it whenever you document one of those elements. Rules for methods and rules that apply to every doc comment stay in this file.

Precedence

When a more specific YARD skill applies, its rules override this general skill:

• Command YARD Documentation overrides these rules for Git::Commands::Base subclasses.
• Facade YARD Documentation overrides these rules for Git::Repository::* topic modules.

Otherwise, the rules in this file apply to all Ruby source.

Workflow

Documenting or fixing YARD docs follows three steps:

1. Step 1: Identify What Needs Documentation
2. Step 2: Write Documentation — apply the templates and the Documentation Standards
3. Step 3: Verify Documentation — lint, build, and manually check

ruby-git uses YARD for API documentation. All classes, modules, constants, attributes, and methods must have YARD documentation. Methods with Ruby private visibility require a short description and all applicable tags from the Method Rules — @param, @return, @raise, @yield/@yieldparam/@yieldreturn, and @overload — with the exception that @example may be omitted unless an example materially clarifies the behavior. Private methods still need YARD docs for developer reference in source, even though YARD excludes them from generated HTML by default.

Named length limits

Three named limits govern line and description length throughout this skill. They are referenced by name in Step 3 and the Formatting Rules:

• LINE_LIMIT (90 characters) — the preferred maximum length of any physical YARD comment line, measured from column 1 and including every character: indentation, #, tag metadata, and all text. Wrap prose at this limit wherever possible.
• LINE_MAX (120 characters) — the hard ceiling for lines that cannot be wrapped without breaking their meaning. The following content may exceed LINE_LIMIT up to LINE_MAX; it must not exceed LINE_MAX:
  • URLs — in @see tags or markdown links; a URL cannot be split
  • Long inline code spans — a `backtick` span whose content alone approaches or exceeds LINE_LIMIT
  • Long [Type] expressions — a type such as [String, Pathname, Array<String, Pathname>] that fills the tag metadata column before any description text begins
  • @example code lines — real code inside an example block that cannot be reflowed without changing its meaning
  • Markdown table rows — pipe-delimited table rows that cannot be split across lines
• SUMMARY_LIMIT (90 characters) — the maximum length of a short description — either a tag's description text or a documentable object's short description (class, module, method, constant, or attribute) — measured by concatenating the text from the first line with all immediately following indented continuation lines (stripping the leading # and continuation indent from each and joining with a single space). For tags, this covers the description text only — not the tag name, [Type], option key, or (default).

Step 1: Identify What Needs Documentation

# Find undocumented objects
bundle exec yard stats --list-undoc

# Check a specific file
bundle exec yard doc lib/git/repository.rb --no-output

Step 2: Write Documentation

Follow the YARD documentation templates below and apply the Documentation Standards as you write. Use the standard template when a method has a single call signature. Use the overload template when a method has distinct call signatures with different parameters or return types.

When @overload blocks are present:

• Keep signature-specific tags inside overload blocks only: @example, @param, @option, @return, overload-specific @raise, and @yield/@yieldparam/@yieldreturn
• Keep @return inside each @overload block. For overloaded methods, @return is overload-scoped even when the return type/text is the same across call shapes
• Keep shared @raise at top level only once (outside all overload blocks)
• Keep @raise inside an overload only when that exception applies to that overload shape only
• Never document the same @raise in both places (top-level and overload)
• Keep non-signature tags (@note, @deprecated, @see, @api) at top level
• Never nest @api inside an @overload block; it applies to the method itself, not to an individual call shape

Correct placement pattern:

# @overload fetch(name)
#
#   @param name [String] the remote name
#
#   @return [Git::CommandLine::Result] the command result
#
# @overload fetch(name, **options)
#
#   @param name [String] the remote name
#
#   @param options [Hash] command options
#
#   @return [Git::CommandLine::Result] the command result
#
# @raise [ArgumentError] when the remote name is invalid
#
# @api public

Incorrect placement pattern:

# @overload fetch(name)
#
#   @param name [String] the remote name
#
# @return [Git::CommandLine::Result] the command result
#
# @raise [ArgumentError] when the remote name is invalid
#
# @overload fetch(name, **options)
#
#   @param name [String] the remote name
#
#   @param options [Hash] command options
#
#   @raise [ArgumentError] when the remote name is invalid
#
#   @api public

Trigger: always use @overload for anonymous *, anonymous **, or ...

Anonymous splats and the forwarding parameter give @param, @option, @yield, and @yieldparam no named parameter to bind to, so YARD silently drops them. Switch to @overload for the entire signature — see Documenting anonymous splats with @overload.

Standard template (no @overload)

When present, tags must appear in the order shown. @param tags appear in parameter order, with one exception described below; @option tags appear immediately after the @param for the hash they describe. Every @option tag must be preceded by a @param for the options hash, and all @option tags under that @param must reference the same parameter name. For keyword arguments (**options or **kwargs), use @param options [Hash] (or the actual splat name) as the preceding @param.

For public APIs with known option keys, every @option tag must document a real supported key, such as :force or :timeout. Do not invent placeholder option keys for a public options hash.

For private helpers that accept arbitrary keyword collectors whose keys are validated elsewhere, use a neutral splat name such as candidate_keywords and document the collector shape with a single pseudo-option entry named key_name. A pseudo-option is required because yard-lint's Documentation/UndocumentedOptions flags any documented ** collector that has no @option tag, and that check has no type, name, or visibility exemption for double-splats. Use key_name rather than a literal-looking key so it is not mistaken for a real option key. This is only for arbitrary-keyword helpers where the accepted keys are intentionally not known at that abstraction layer:

# Validate that candidate option keys are listed in `allowed`
#
# @param allowed [Array<Symbol>] the permitted option keys
#
# @param candidate_keywords [Hash<Symbol, Object>] the keywords to validate
#
# @option candidate_keywords [Object] key_name a candidate keyword value
#
# @return [void]
#
# @raise [ArgumentError] when any candidate key is not in `allowed`
#
def assert_valid_opts!(allowed, **candidate_keywords)
end

The exception to parameter order: all @param tags must come before the first @option tag, because yard-lint's Tags/Order validator rejects a @param that follows an @option. When a positional parameter follows the options hash in the signature, document the options-hash @param (and its @option tags) last so the @option tags stay grouped at the end — that is, move the options-hash @param after the later positional @param rather than in strict signature order:

# Short description of what the method does
#
# Longer description with more details about behavior,
# edge cases, or important notes.
#
# @example Basic usage
#   git = Git.open('/path/to/repo')
#   result = git.method_name('arg', {}, '/path')
#
# @example With options
#   git.method_name('arg', { option: true }, '/path')
#
# @param name [Type] description of parameter
#
# @param path [String] a parameter that follows the options hash in the signature
#
# @param options [Hash] options hash description
#
# @option options [Type] :key description of option
#
# @return [Type] description of return value
#
# @raise [ArgumentError] when invalid arguments are provided
#
# @raise [Git::FailedError] when git exits with a non-zero exit status
#
# @yield [commit] passes each commit to the block
#
# @yieldparam commit [Git::Object::Commit] a commit object
#
# @yieldreturn [void]
#
# @note This method is not thread-safe
#
# @deprecated Use {#new_method} instead
#
# @see #related_method
#
# @see Git::RelatedClass
#
# @see https://git-scm.com/docs/git-log
#
# @api public
#
def method_name(name, options = {}, path)
end

Overload template

Each @overload block carries only signature-specific tags: @example, @param, @option, @return, overload-specific @raise, and @yield/@yieldparam/@yieldreturn. Tags that are not call-signature-specific — @note, @deprecated, @see, @api — remain at the top level. @return remains overload-scoped even when identical across call shapes. @raise can be top-level when shared across all call shapes, and overload-local when shape-specific. Never place @api inside an overload block.

# Short description of what the method does
#
# Longer description with more details about behavior,
# edge cases, or important notes.
#
# @overload method_name(arg)
#
#   Single-argument form description
#
#   @example Basic usage
#     result = git.method_name('arg')
#
#   @param arg [String] the argument
#
#   @return [String] the result
#
# @overload method_name(arg, options)
#
#   Two-argument form description
#
#   @example With options
#     result = git.method_name('arg', { force: true })
#
#   @param arg [String] the argument
#
#   @param options [Hash] additional options
#
#   @return [Array<String>] the results
#
# @raise [ArgumentError] when an invalid argument is provided
#
# @note This method is not thread-safe
#
# @deprecated Use {#new_method} instead
#
# @see #related_method
#
# @see https://git-scm.com/docs/git-log
#
# @api public
#
def method_name(arg, options = {})
end

Overload decision matrix

Use this matrix to decide whether to use @overload and where to place tags:

Documenting anonymous splats with @overload

When the method signature uses an anonymous splat — def foo(*), def foo(**), def foo(*, **) — or the argument forwarding parameter def foo(...) — @param, @option, @yield, and @yieldparam tags have no parameter name to bind to. RuboCop's Style/ArgumentsForwarding cop prefers these forms when arguments are forwarded unchanged, so naming the splat (or expanding ... into *args, **kwargs, &block) is not an acceptable workaround. Use @overload blocks that introduce named parameters for documentation purposes only:

# Update the index with the current content found in the working tree
#
# @overload add(paths = '.', **options)
#
#   @example Stage a specific file
#     git.add('README.md')
#
#   @param paths [String, Array<String>] file(s) to add (relative to the
#     worktree root); defaults to `'.'` (all files)
#
#   @param options [Hash] command options
#
#   @option options [Boolean, nil] :all (nil) add, modify, and remove index entries to
#     match the worktree
#
#   @option options [Boolean, nil] :force (nil) allow adding otherwise ignored files
#
#   @return [String] the command output
#
#   @raise [Git::FailedError] if `git add` exits with a non-zero status
#
def add(paths = '.', **)
  Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
end

The same approach applies to .... The overload signature names the parameters; the actual def keeps ... so RuboCop is satisfied:

# Run a command against the underlying execution context
#
# @overload run(command, *args, **options, &block)
#
#   @example Run git status
#     result = git.run('status')
#
#   @param command [String] the git subcommand to run
#
#   @param args [Array<String>] positional arguments forwarded to the command
#
#   @param options [Hash] keyword options forwarded to the command
#
#   @return [Git::CommandLine::Result] the command result
#
#   @yield [result] yields the command result, when a block is given
#
#   @yieldparam result [Git::CommandLine::Result] the command result
#
#   @yieldreturn [void]
#
def run(command, ...)
  Git::Commands::Run.new(@execution_context).call(command, ...)
end

When a method has multiple genuinely distinct call shapes, write one @overload block per shape as in the Overload template above.

Anonymous block parameter (&) is not covered by this rule. @yield, @yieldparam, and @yieldreturn describe what is yielded to the block, not the block parameter itself, so they bind correctly even with an anonymous &. Use a named block parameter (&block) and a @param block [Proc] tag only in the rare case where the block is documented as a first-class Proc value (stored, returned, or passed elsewhere) rather than yielded to.

Documenting other elements

The templates above cover methods. When documenting a class, module, constant, attribute, dynamically defined method (@!method), or a value object (Data.define / Struct.new), follow the per-element requirements in element-rules.md.

Step 3: Verify Documentation

First, run the automated linter. yard-lint enforces many of the rules in this skill (undocumented objects, missing @param/@option/@return, tag order, type syntax, orphaned doc comments) and the minimum documentation coverage threshold:

# Lint YARD docs against the project standards (config: .yard-lint.yml)
bundle exec yard-lint lib/

# Lint only the files you changed
bundle exec yard-lint lib/ --diff main

# Or run it through rake (build + lint + example-test)
bundle exec rake yard

A clean yard-lint run is necessary but not sufficient: the linter cannot check every rule here (e.g. the LINE_LIMIT/LINE_MAX distinction, SUMMARY_LIMIT, short-description capitalization and punctuation, noun-phrase class descriptions, required @example titles, class/module-level @api visibility correctness). Still perform the manual checks below.

Legacy offenses are baselined in .yard-lint-todo.yml; when you touch a file listed there, remove it from every Exclude: list that names it (a file may be baselined under more than one validator) and fix the offenses as part of your change.

Then generate and review the rendered docs:

# Generate and review docs
bundle exec yard doc
# then open doc/index.html in your browser

# Check for warnings
bundle exec yard doc 2>&1 | ruby -ne 'puts $_ if $_ =~ /warn/i'

Verify @example code runs correctly in bundle exec bin/console. Check that all @see references point to valid targets.

Line and summary length checks

Apply these checks to every YARD doc comment — the description on a class, module, method, constant, or attribute, and every tag within it (@param, @return, @raise, @option, @yield, @yieldparam, @yieldreturn, etc.). Check all three limits:

1. LINE_LIMIT: Count every character from column 1 (indentation, #, metadata, text) on each physical line. If any wrappable line exceeds LINE_LIMIT, split at a word boundary onto a continuation line (indented two extra spaces). Apply this check to every continuation line independently.
2. LINE_MAX: Confirm no physical line exceeds LINE_MAX — the hard ceiling that nothing may cross. Only unwrappable content (URLs, long inline code spans, long [Type] expressions, @example code, markdown table rows) may sit between LINE_LIMIT and LINE_MAX; every other line must stay within LINE_LIMIT.
3. SUMMARY_LIMIT: For each short description — a tag's description or a documented object's short description — strip the leading # and its indentation from every continuation line and join with a single space. If the concatenated text exceeds SUMMARY_LIMIT, shorten it and move the excess into a paragraph after a blank # line.

Documentation Standards

The rules below are the reference the Workflow draws on. The Formatting Rules apply to every doc comment regardless of element type; the Method Rules govern method doc comments. Per-element rules for classes, modules, constants, attributes, and value objects are in element-rules.md.

Treat every rule in this section as mandatory unless its heading is marked (SHOULD) or (Optional). Headings that name a descriptive topic (e.g. type-specifier conventions) are reference material; any obligations they carry are stated with “must” inline.

Formatting Rules

Doc comments are rendered as markdown via the redcarpet gem. Write all free-text descriptions, tag values, and examples using markdown syntax. These rules apply to all documentation regardless of element type. They reference the three Named length limits (LINE_LIMIT, LINE_MAX, SUMMARY_LIMIT) defined earlier.

Doc comment placement

YARD doc comments must appear immediately above the element they document (class, module, method, constant, or attribute) with no intervening blank lines or non-comment code.

Blank lines around tags

Every individual YARD tag must be preceded by a blank comment line (#) unless it is the very first line of a doc comment. A YARD tag is any comment token matching @!?[a-z_]+ — that is, @word (regular tags such as @param, @return, @raise, @api, @abstract, @deprecated, etc.) or @!word (directives such as @!attribute, @!method, @!scope, etc.).

Within the tag block there are no other exceptions: consecutive same-kind tags (e.g. multiple @param lines) each require their own preceding blank line.

Never use raw blank lines inside a doc comment block

A raw blank line — an empty line with no leading # — terminates the YARD doc comment block at that point. Any comment lines that follow the raw blank line are treated as separate, unattached comments and will not appear in the generated documentation. Always use a blank comment line (#) to separate paragraphs or continuation text within a YARD block:

Correct — blank comment line keeps the block intact:

# @option options [Boolean, nil] :ipv4 (nil) use IPv4 addresses only
#
#   Alias: :"4"

Incorrect — raw blank line silently drops the alias note:

# @option options [Boolean, nil] :ipv4 (nil) use IPv4 addresses only

#   Alias: :"4"

Watch for editors that auto-strip trailing spaces from # lines, silently creating raw blank lines.

Short descriptions

The short description (the first sentence of any doc comment, or the inline text of a @param, @return, @raise, etc. tag) must:

• Be a single sentence
• Not end with sentence-ending punctuation (., ?, !)
• Element-level short descriptions (on classes, modules, and methods) start with an uppercase letter (e.g. Returns the commit count, Represents a Git branch)
• Tag short descriptions (@option, @param, @return, @raise, @yield, @yieldparam, etc.) all start with a lowercase letter (e.g. @option options [Boolean, nil] :force (nil) overwrite existing files, @param name [String] the branch name, @return [String] the result, @raise [ArgumentError] when no name is provided)

For tags, the summary text is the description that follows the tag metadata (tag name, [Type], option key, and (default)). For example, in:

@option options [Boolean, nil] :ignore_case (nil) ignore case distinctions

the summary text is ignore case distinctions.