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

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
`@raise` tags	One `@raise` tag per exception class — never group multiple exceptions
`.call` / complex returns	`@return` MUST specify exact structure (e.g., `[Hash] Result with :success and :response keys`)
Tagged notes	`TODO:`, `FIXME:`, `HACK:`, `NOTE:`, `OPTIMIZE:` must carry actionable context (owner, ticket, next step); no naked tags
Language	English unless user explicitly requests otherwise