Command-specific YARD documentation rules for Git::Commands::Base subclasses, overriding and extending the general yard-documentation skill. Use when writing or reviewing YARD docs for command classes.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Command-specific YARD documentation rules for Git::Commands::Base subclasses, overriding and extending the general yard-documentation skill. Use when writing or reviewing YARD docs for command classes.
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.
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:
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
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:
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::CommandLineResult] the result of calling `git log`## @raise [ArgumentError] if conflicting options are given## @raise [Git::FailedError] if git exits with a non-zero exit statusdefcall(*, **kwargs)
# custom logic …superend
Using @!method when def call already exists causes YARD to generate duplicate or
conflicting documentation for the method.
DSL-to-YARD type mapping
DSL method
YARD type
flag_option
[Boolean, nil] — default (nil) (flag not emitted by default; both false and nil suppress the flag)
[String] — value_option does not enforce types; it accepts any non-nil value and converts it to a string. Use [String] unless callers are expected to pass a narrower type, in which case widen the annotation to reflect reality (e.g. [Integer, String] for options documented as taking <n> lines/bytes). Never use a bare numeric type such as [Integer] alone — that misrepresents what the implementation accepts.
operand (repeatable)
[Array<String>]
operand (single)
[String]
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:
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.
Workflow
For each command file, run through these checks in order:
1. Class-level docs
one-line summary
brief behavior description
@example blocks with representative usage
@note `arguments` block audited against https://git-scm.com/docs/git-{command}/<version> —
present and recording the latest git version at the time of the last DSL audit.
Flag as an error if missing or if the version in the URL does not match the
current latest git version (run bin/latest-git-version from the repo root to
check; a stale version means the DSL may be missing options added in later releases)
@see to parent command module where applicable
@see to the full documentation URL (e.g., @see https://git-scm.com/docs/git-show-ref)
@api private
2. Arguments docs
@overload blocks cover valid call shapes
every positional arg has @param
every applicable option has @option
@option entries appear in the same order as the corresponding entries in the
arguments do block
@option defaults match the DSL method — flag_option (plain or negatable)
always uses (nil) for both the positive and negative no_ companion tag;
value_option uses (nil). Check every @option default tag against the DSL entry.
For negatable: options, verify that two@option tags are present (one
for the positive key, one for the no_ companion key) and that both use (nil).
option defaults/types are consistent with DSL definitions
@option descriptions for options that have an allowed_values declaration
enumerate the accepted values in the description text, e.g.: @option options [String] :cleanup (nil) Cleanup mode — one of verbatim, whitespace, or strip
3. Return and raise tags
@return [Git::CommandLineResult] with wording: "the result of calling git <subcommand>"
@api public is present at the end of the @overload block (after all @raise
tags) — every command class is @api private at the class level, but call is
the public contract and must be marked @api public
whenever the @overload signature includes **options, include
@raise [ArgumentError] if unsupported options are provided — the Arguments
DSL always raises this at bind time for unknown keys via validate_unsupported_options!
@raise [Git::FailedError] uses the canonical generic wording — never
enumerate specific failure causes; use the form that matches the command's
declared exit-status range:
allow_exit_status
Canonical @raise wording
none declared (default 0..0)
if git exits with a non-zero exit status
allow_exit_status 0..1
if git exits outside the allowed range (exit code > 1)
allow_exit_status 0..N
if git exits outside the allowed range (exit code > N)
4. allow_exit_status rationale consistency
When command declares non-default exit range:
includes short rationale comment above declaration
YARD @raise text does not contradict accepted status behavior
5. Formatting consistency
every YARD tag (@param, @option, @return, @raise, @overload,
@see, @api, etc.) is preceded by a blank comment line (#)
no raw blank lines (lines with no leading #) appear inside any doc block —
a raw blank line silently terminates the block and drops everything after it
tag short descriptions (the first sentence of each @param, @option,
@return, @raise, etc.) do not end with punctuation (no ., ,, ;, :)
multi-paragraph tag descriptions have a blank comment line (#) between the
short description and each continuation paragraph
@option, @param, @return, and @raise short descriptions all start with a
lowercase letter (e.g. show the HEAD ref even when filtered, the path to the repository, the result of calling \git show-ref`, if git exits with a non-zero
status`)
consistent option wording and defaults across sibling commands
max_times: flags use [Boolean, Integer] type, not just [Boolean], and
include a continuation paragraph explaining integer semantics (e.g. "When an
integer is given, the flag is repeated that many times")
no stale references to removed per-command implementation details
all other general formatting rules from YARD
Documentation are satisfied
6. Avoid internal implementation detail leakage
Prefer interface-level wording (what callers can pass/expect), not internals.
Common example — stdin transport mechanism:
# Bad: leaks implementation detail (IO pipe, threading)# Object names are written to the process's stdin via an in-memory IO pipe;# this avoids spawning additional processes and works with the --batch protocol.# Good: describes caller-facing behavior# Object names are passed to the git process's stdin using the --batch protocol.
description does not mention IO.pipe, threads, or pipe buffer management
description does not reference internal method names (with_stdin,
run_batch)
description describes what the caller passes and what they get back
Output
When writing new YARD docs
Produce the complete YARD doc block(s) for the command class, then self-verify
by running every checklist item from Workflow against your output.
If any issues are found, fix and re-verify until all checks pass.
When reviewing existing YARD docs
For each file, provide:
issue table
Check
Status
Issue
corrected doc block snippets (only where needed)
Self-verify before concluding — after writing corrected snippets, re-run
every checklist item from Workflow against your proposed
snippets. If any new issues are found, update the snippets and repeat until all
checks pass. Only then write the final issue table marking everything as passing.
Branch workflow: Implement any fixes on a feature branch. Never commit or push
directly to main — open a pull request when changes are ready to merge.
