Command Yard Documentation

Command YARD Documentation

Write and verify YARD documentation for command classes aligned with the Git::Commands::Base pattern. Use this skill when writing or reviewing YARD docs on command classes — it overrides and extends the general YARD Documentation skill with command-specific rules.

This skill verifies that YARD docs accurately mirror the arguments do block as-implemented. It does not re-adjudicate which options belong based on Git version — version gating is the domain of the DSL and the Command Implementation skill, not YARD review.

Contents

• Contents
• Related skills
• Input
• Reference
  • Required documentation model
    • No def call override (simple commands)
    • Explicit def call override
  • DSL-to-YARD type mapping
  • Common issues
• Workflow
  • 1. Class-level docs
  • 2. Arguments docs
  • 3. Return and raise tags
  • 4. allow_exit_status rationale consistency
  • 5. Formatting consistency
  • 6. Avoid internal implementation detail leakage
• Output
  • When writing new YARD docs
  • When reviewing existing YARD docs

Related skills

• YARD Documentation — authoritative source for general YARD formatting rules and writing standards
• Review Arguments DSL — verifying DSL entries match git CLI
• Command Implementation — class structure, phased rollout gates, and internal compatibility contracts
• Command Test Conventions — unit/integration test conventions for command classes

Input

Before starting, you MUST load the following skill(s) in their entirety:

• YARD Documentation — authoritative source for YARD formatting rules and writing standards

Then gather the following for each command under review:

1. Command source — one or more files from lib/git/commands/ containing:

   • class < Git::Commands::Base
   • arguments do ... end
   • optional allow_exit_status
   • either a # @!method call(*, **) YARD directive (when no def call override) or YARD doc comments directly above an explicit def call override

2. Git documentation for the git command

   • Latest-version online command documentation

     Read the entire official git documentation online man page for the command for the latest version of git. This version will be used as the primary authority for verifying option names, aliases, descriptions, and ordering. Fetch this version from the URL https://git-scm.com/docs/git-{command} (this URL always serves the latest release).

   • Minimum-version online command documentation

     Read the entire official git documentation online man page for the command for the Git::MINIMUM_GIT_VERSION version of git. This will be used to confirm whether the command/class is gated by requires_git_version and, when it is, that the YARD docs include a continuation paragraph noting the minimum version requirement. Fetch this version from the URL https://git-scm.com/docs/git-{command}/{version}.

   Do not rely on local git <command> -h output — the installed Git version is unknown and may differ from the minimum or latest supported version.

Reference

Required documentation model

The placement of call documentation depends on whether the command class overrides def call.

No def call override (simple commands)

When the class does not define def call, use the # @!method call(*, **) YARD directive. This tells YARD to attach per-command docs to the inherited call method without a method definition in the subclass:

# @!method call(*, **)
#
#   @overload call(**options)
#
#     Execute the git ... command.
#
#     @param options [Hash] command options
#
#     @option options [Boolean, nil] :force (nil) ...
#
#     @return [Git::CommandLine::Result]

Note the placement rules:

• The @overload description text must appear inside the @overload block (indented one extra level, as in the template above). Do not place the description between the @!method line and the @overload tag — that level belongs to any @!method-scope prose that is not part of any overload, which is rarely needed.
• Place the directive inside the class body, after the arguments do block (and after allow_exit_status when present). Do not combine @!method with an explicit def call.

Explicit def call override

When the class defines def call explicitly (for input validation, stdin feeding, or non-trivial option routing), place YARD docs directly above the def call method. Do not use @!method — YARD will read the normal doc comment on the real method:

# @overload call(*revision_range, **options)
#
#   Execute the `git log` command.
#
#   @param revision_range [Array<String>] zero or more revision specifiers
#
#   @param options [Hash] command options
#
#   @option options [Boolean, nil] :all (nil) ...
#
#   @return [Git::CommandLine::Result] the result of calling `git log`
#
#   @raise [ArgumentError] if conflicting options are given
#
#   @raise [Git::FailedError] if git exits with a non-zero exit status
def call(*, **kwargs)
  # custom logic …
  super
end

Using @!method when def call already exists causes YARD to generate duplicate or conflicting documentation for the method.

DSL-to-YARD type mapping

Common issues

• Using # @!method call(*, **) when an explicit def call override exists — causes YARD to generate duplicate or conflicting documentation; remove the @!method directive and place the @overload docs directly above def call

• Missing # @!method call(*, **) directive when there is no def call override (loses child-specific docs in generated YARD)

• @option docs out of sync with arguments do

• YARD tags inside the arguments do block — placing a tag (@see, @param, @return, etc.) in a comment above a DSL entry such as flag_option :x produces an orphaned doc comment. The DSL call is not a documentable construct, so YARD silently drops the comment and Documentation/OrphanedDocComment flags it. Document each option in its @option tag (put URLs in continuation text) and use a class-level @see for command-wide references. A plain-prose comment (no leading @tag) inside the block is fine.

• Missing @raise [ArgumentError] when **options is in the overload signature — every @overload that includes **options requires @raise [ArgumentError] if unsupported options are provided. The Arguments DSL always raises this at bind time for unknown keys via validate_unsupported_options!. For commands whose arguments block declares no options (only operand entries), drop **options from the signature entirely — then no @raise [ArgumentError] is needed.

• **options in @overload without @param options [Hash] — whenever an @overload signature includes **options, a corresponding @param options [Hash] tag is required. For commands whose arguments block declares no options (only operand entries), omit **options from the @overload signature entirely and remove any @raise [ArgumentError] if unsupported options are provided tag.

  # ❌ No options in DSL but **options appears in overload without @param
  #   @overload call(name, **options)
  #     @param name [String] the remote name to remove
  #     @raise [ArgumentError] if unsupported options are provided
  
  # ✅ Operand-only command: drop **options from the signature
  #   @overload call(name)
  #     @param name [String] the remote name to remove

• Missing second @option tag for negatable: options — when the DSL declares flag_option :foo, negatable: true or flag_or_value_option :foo, negatable: true, two separate @option entries are required: one for the positive key (:foo) and one for the negative companion key (:no_foo). A single tag documents only half the interface.

  # ❌ Missing negative companion tag
  # @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
  
  # ✅ Both forms documented with separate tags
  # @option options [Boolean, nil] :create_reflog (nil) create the branch's reflog
  #
  # @option options [Boolean, nil] :no_create_reflog (nil) suppress branch reflog
  #   creation (`--no-create-reflog`)

• Missing/incorrect @raise guidance for allow_exit_status

• Overly specific @raise [Git::FailedError] description — do not enumerate specific failure causes (e.g., "if the branch doesn't exist", "if the target already exists"). Git can fail for many reasons beyond any list (invalid ref name, not a git repository, permission error, etc.). Use the generic range-based form:

  # ❌ Overly specific — does not cover all failure cases
  # @raise [Git::FailedError] if the branch doesn't exist or target exists (without force)
  
  # ✅ Correct — generic, matches sibling commands, accurate for all failure causes
  # @raise [Git::FailedError] if git exits with a non-zero exit status

  For commands with a non-default range (e.g. allow_exit_status 0..1):

  # ✅ Correct for allow_exit_status 0..1
  # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)

• Legacy references to ARGS constant or command-specific initialize

• @option description references a short flag instead of the emitted long flag — @option prose must describe behavior using the emitted CLI form (the long flag), not the git man-page synopsis short notation. The DSL emits the primary (long) flag regardless of which alias the caller uses.

  # ❌ Wrong — describes -v as if it is emitted
  # @option options [Boolean, Integer, nil] :verbose (nil) ...
  #   Pass `true` for `-v`; pass `2` for `-v -v`.
  
  # ✅ Correct — describes the actually emitted flag
  # @option options [Boolean, Integer, nil] :verbose (nil) ...
  #   Pass `true` for `--verbose`; pass `2` for `--verbose --verbose`.

• Description leaks internal mechanics (e.g., "written via IO pipe") instead of describing caller-facing behavior

• Uppercase first letter or trailing period on tag short descriptions — the summary text of every @option, @param, @return, and @raise tag must start with a lowercase letter and must not end with punctuation (., ,, ;, :). Git man pages start descriptions with uppercase and end them with periods; both mistakes are easy to copy verbatim. Run bundle exec rake yard to catch trailing periods — YARD treats any failure as fatal. Correct form:

  # ❌ Copied verbatim from the git man page
  # @option options [Boolean, nil] :force (nil) Allow renaming even if target already exists.
  
  # ✅ Correct — lowercase start, no trailing period
  # @option options [Boolean, nil] :force (nil) allow renaming even if target already exists

• Raw blank line inside a doc comment block — a raw blank line (an empty line with no leading #) silently terminates the YARD block. Any comment lines after the raw blank line are dropped from generated docs. Replace every raw blank line inside a block with a blank comment line (#). This is easy to miss in continuation paragraphs and alias notes. Correct form:

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

• Multi-sentence short description without a blank comment line — when an @option needs more than one sentence, the first sentence is the short description and all additional detail must go in a continuation paragraph separated by a blank # line. Writing both sentences on the same run-in line violates YARD's short-description rule. Correct form:

  # @option options [Boolean, nil] :update_head_ok (nil) allow updating HEAD ref
  #
  #   When true, passes --update-head-ok. By default git fetch refuses to update HEAD.