Write YARD Docs

Use this skill when documenting Ruby classes and public methods with YARD.

Core principle: Every public class and public method has YARD documentation so the contract is clear and tooling can generate API docs.

Quick Reference

HARD-GATE

AFTER IMPLEMENTATION GATE:
After any feature or fix that adds or changes public Ruby API (classes, modules, public methods):
1. Add or update YARD on those surfaces before the work is considered done.
2. All YARD text must be in English unless user explicitly requests otherwise.
Task lists from generate-tasks MUST include explicit YARD sub-tasks after implementation.

Core Process

1. Identify Public Surfaces: Locate all new or modified public classes, modules, and methods.
2. Add Class-Level Docs: Provide a one-line summary describing the responsibility of the class or module.
3. Add Method-Level Docs: For every public method, add @param (and @option for hash arguments), @return, and @raise tags.
4. Document Exceptions: List each exception separately with its own @raise tag, even if the method rescues it internally.
5. Verify Completeness: Run yard stats --list-undoc and yard doc to ensure no public surfaces are missing documentation.
6. Task-list handoff: When producing or reviewing tasks from generate-tasks, add explicit YARD sub-tasks after implementation for every new or changed public Ruby API.

Tag Examples

Class-level

# Responsible for validating and executing animal transfers between shelters.
# @since 1.2.0
module AnimalTransfers
  class TransferService

Method-level

# Performs the transfer and returns a standardized response.
# @param params [Hash] Transfer parameters
# @option params [Hash] :source_shelter Shelter hash with :shelter_id
# @option params [Hash] :target_shelter Target shelter with :shelter_id
# @return [Hash] Result with :success and :response keys
# @raise [InvalidShelterError] when the shelter does not exist
# @example Basic usage
#   result = TransferService.call(source_shelter: { shelter_id: 1 }, target_shelter: { shelter_id: 2 })
#   result[:success] # => true
def self.call(params)

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

• EXAMPLES.md — Canonical examples for common tags, including @param, @return, and @raise tag usage.
• references/tagged-notes.md — Guidelines on tagged notes (TODO:, FIXME:).
• ADVANCED_TAGS.md — Guidance for advanced tags (@abstract, @deprecated, @api private, @yield, @overload).

Output Style

When writing or reviewing YARD docs, your output MUST satisfy:

1. Class/Module Summary — Every new or modified public class/module has a descriptive summary.
2. Method Tags — Every public method must have @param (or @option), @return, and @raise tags.
3. Discrete @raise Tags — One @raise tag per exception class. Do not group multiple exceptions into a single tag.
4. Explicit Return Structures — For .call methods or complex returns, the @return tag MUST specify the exact structure (e.g., [Hash] Result with :success and :response keys).
5. Tagged Notes Context — Inline tagged notes (TODO:, FIXME:, HACK:, NOTE:, OPTIMIZE:) must carry actionable context (owner, ticket, next step). No naked tags.
6. Generate-tasks handoff — If the output is a task list, include YARD documentation sub-tasks after implementation tasks. If the output is only a documentation artifact, state that future generate-tasks output must include those YARD sub-tasks.
7. Language — Must be in English unless explicitly requested otherwise.

Integration