yard-documentation

YARD Documentation

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.

HARD-GATE: After implementation

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.

Tag Reference

Canonical examples for common tags: EXAMPLES.md — includes @param, @return, and @raise tag usage.

Scope	Rule
Classes	One-line summary; optional @since if version matters
Public methods	All tags required unless explicitly inapplicable: @param, @option (for hash params), @return, @raise
Public initialize	Add @param for constructor inputs when initialization is part of the public contract
Private methods	Document only if behavior is non-obvious; same tag rules

Standard Tags with Examples

Class-level

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

Method-level: params, options, return, and example

Use @option for every valid key in hash params. Include at least one @example on .call or the main public entry point.

# 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
# @example Basic usage
#   result = TransferService.call(source_shelter: { shelter_id: 1 }, target_shelter: { shelter_id: 2 })
#   result[:success] # => true
def self.call(params)

Method-level: exceptions

Document @raise for every exception a method can raise — even if the method rescues it internally. One tag per exception class.

# Processes the billing update for the given plan.
# @param plan_id [Integer] ID of the target plan
# @raise [InvalidPlanError] when the plan does not exist or is inactive
# @raise [PaymentGatewayError] when the payment provider rejects the charge
# @return [Hash] Result with :success and :response keys
def self.call(plan_id:)

Nullable / conditional returns

# Validates source and target shelters and returns the first validation error.
# @param source_id [Integer] Source shelter ID
# @param target_id [Integer] Target shelter ID
# @return [nil, String] nil if valid, error message otherwise
def self.validate_shelters!(source_id, target_id)

Anti-pattern

# Updates billing.  (Too vague; no @param/@return/@raise)
def self.call(plan_id:)

Pitfalls

Pitfall	What to do
Documenting only the class, not public methods	Callers need param types and return shape for every public method
Skipping @option for hash params	Without it, consumers don't know valid keys or types
Only one @raise for multiple exceptions	List EVERY exception type — one @raise per class, even if rescued internally
YARD text in a language other than English	Write in English unless the user explicitly requests otherwise

Inline tagged notes

YARD documents the contract; tagged notes (TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE:) document the why on the same code. Every tag carries actionable context (owner, ticket, next step); naked tags fail review. See references/tagged-notes.md and rails-code-conventions.

Verification

Run validation before considering documentation complete:

1. yard stats --list-undoc
2. yard doc
3. If output shows undocumented public surfaces you changed, update YARD and re-run.

For advanced tags (@abstract, @deprecated, @api private, @yield, @overload) see ADVANCED_TAGS.md.

Integration

Skill	When to chain
ruby-service-objects	Implementing or documenting service objects
ruby-api-client-integration	Documenting API client layers (Auth, Client, Fetcher, Builder)
rails-engine-docs	Documenting engine public API or extension points
rails-code-review	Reviewing that public interfaces are documented
generate-tasks	Generated task lists include YARD tasks after implementation