Documentation with YARD
YARD turns Ruby source into navigable API docs. We annotate service objects, public libraries, and helper modules so contributors can discover contracts quickly. Use YARD in tandem with RuboCop’s documentation cops to keep interfaces discoverable.
Install & Initialize
Store `.yardopts` at the project root. Include directories we want documented (e.g., `app/services`, `lib`).
Annotate Public APIs
Use YARD’s tags (`@param`, `@return`, `@raise`, `@example`) to document contracts. Group related methods with `@!group` so the generated docs reveal module cohesion.
Generate & Publish
Publish docs alongside deployments or as part of an internal handbook. If we ship a gem, add `yard` to the release pipeline so external consumers get fresh docs with every version.
Review Checklist
- Every public method in a service object has `@param` and `@return` annotations.
- Callbacks, background jobs, and CLI entry points include `@example` snippets.
- Docs rebuild cleanly (`bundle exec yard stats`) with zero undocumented public objects.
- Link YARD sections from README or internal docs so developers know where to look.