Epic: YARD API Documentation Migration #92

New issue

Open

opened 2026-03-15 04:13:08 +00:00 by freemo · 0 comments

freemo commented

2026-03-15 04:13:08 +00:00

Owner

Metadata

Commit Message: chore(docs): migrate from RDoc to YARD
Branch: feature/yard-migration

Background and Context

The specification lists YARD as the API documentation tool, but the codebase currently
uses RDoc (rdoc ~> 4.2 in gemspec, Rake::RDocTask in Rakefile). YARD provides
richer documentation features including @param, @return, @raise tags,
cross-references, and better HTML output.

Expected Behavior

All API documentation is generated by YARD. The yard gem replaces rdoc as a
dependency. The Rakefile uses YARD::Rake::YardocTask. Existing doc comments are
converted to YARD's @tag format.

Acceptance Criteria

yard gem replaces rdoc in gemspec
Rakefile uses YARD::Rake::YardocTask
Existing doc comments use YARD @tag format
rake yard generates documentation successfully
CONTRIBUTING.md references YARD

Subtasks

Replace RDoc gem dependency with YARD
Update Rakefile to use YARD task
Convert doc comments to YARD format
Update CONTRIBUTING.md

Definition of Done

This Epic is complete when all child issues are closed and all acceptance criteria
are satisfied.

## Metadata - **Commit Message**: `chore(docs): migrate from RDoc to YARD` - **Branch**: `feature/yard-migration` ## Background and Context The specification lists YARD as the API documentation tool, but the codebase currently uses RDoc (`rdoc ~> 4.2` in gemspec, `Rake::RDocTask` in Rakefile). YARD provides richer documentation features including `@param`, `@return`, `@raise` tags, cross-references, and better HTML output. ## Expected Behavior All API documentation is generated by YARD. The `yard` gem replaces `rdoc` as a dependency. The Rakefile uses `YARD::Rake::YardocTask`. Existing doc comments are converted to YARD's `@tag` format. ## Acceptance Criteria - `yard` gem replaces `rdoc` in gemspec - Rakefile uses `YARD::Rake::YardocTask` - Existing doc comments use YARD `@tag` format - `rake yard` generates documentation successfully - CONTRIBUTING.md references YARD ## Subtasks - [ ] Replace RDoc gem dependency with YARD - [ ] Update Rakefile to use YARD task - [ ] Convert doc comments to YARD format - [ ] Update CONTRIBUTING.md ## Definition of Done This Epic is complete when all child issues are closed and all acceptance criteria are satisfied.