yard-lint をCIに追加し、YARDドキュメントの品質を継続的に担保
view_componentプロジェクトに yard-lint を導入し、YARDドキュメントの静的検査をCIパイプラインに組み込みました。既存の違反をあわせて修正することで、ドキュメント品質のベースラインを確立しています。
背景
Issue #2567 で指摘されていたとおり、yard-lint をローカルで実行すると多数のドキュメントエラーが検出される状態が続いていました。チェックを自動化する仕組みがなかったため、新たな違反が混入しても気付けない状況でした。
本PRはこの問題に対処するため、yard-lint をGemfileに追加し、GitHubActionsのlintワークフローに新ジョブとして組み込みました。あわせて既存のルール違反のうち修正件数が少ないものを解消し、CIをグリーンな状態でスタートさせています。
技術的な変更
CI設定と依存関係の追加
.github/workflows/lint.yml に yard-lint ジョブが追加され、bundle exec yard-lint lib/ がCIで実行されるようになりました。Gemfile には gem "yard-lint", "~> 1.5" が追加され、バージョン 1.5.1 が Gemfile.lock に固定されています。
yard-lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 4.0
bundler-cache: true
- name: YARD Lint
run: bundle exec yard-lint lib/
.yard-lint.yml によるルール設定
新規追加された .yard-lint.yml では、有効化するバリデーターと除外パスを明示的に設定しています。vendor/・spec/・test/・performance/ 配下はすべてチェック対象外です。
有効化されているルールは以下のとおりです：
-
Documentation/UndocumentedBooleanMethods: booleanを返すメソッドへのドキュメント必須化 -
Documentation/MarkdownSyntax: コメント内のMarkdown構文チェック -
Documentation/EmptyCommentLine: 空のコメント行の検出 -
Tags/Order: YARDタグの順序チェック -
Tags/InvalidTypes: タグの型指定の妥当性チェック -
Tags/TypeSyntax: タグの型構文チェック
一方、Documentation/UndocumentedObjects や Documentation/MissingReturn など違反数が多いルールは Enabled: false となっており、段階的な修正を前提とした設定になっています。また FailOnSeverity: error により、error レベルの違反のみがCIを失敗させます。
既存ドキュメントの修正
今回のCIグリーン化に伴い、3ファイルで既存のYARDコメントが修正されています。
lib/view_component/compiler.rb では @param タグと @return タグの順序が入れ替わりました。yard-lint の Tags/Order ルールは @param → @return の順序を要求するため、従来の @return → @param の記述が違反と判定されていました。
# 変更前
# @return all matching compiled templates, in priority order based on the requested details from LookupContext
#
# @param [ActionView::TemplateDetails::Requested] requested_details i.e. locales, formats, variants
# 変更後
# @param requested_details [ActionView::TemplateDetails::Requested] i.e. locales, formats, variants
# @return all matching compiled templates, in priority order based on the requested details from LookupContext
lib/view_component/test_helpers.rb では2点の修正が行われました。@param variants と @param formats の型表記が Symbol[] から Array<Symbol> に変更され、Tags/TypeSyntax に準拠した構文になっています。また render_preview メソッドのコメント内にあった通常の説明文が @note タグに変換され、Tags/Order（@param・@return より前にタグなし本文が来ない）を満たす形に整理されています。
lib/view_component/slot.rb では method_missing 直前の末尾空コメント行（#のみの行）が削除され、Documentation/EmptyCommentLine 違反が解消されました。
設計判断
段階的導入の方針が FailOnSeverity: error と多数のルールの無効化に表れています。全ルールを一度に有効化すると大量の違反が発生してCIが通らなくなるため、まず修正容易なルールのみを有効化し、残りは Enabled: false で先送りしています。PRの説明文にも「後で残りを整理する」という意図が明示されており、この設定ファイルは将来的なルール追加の起点として機能します。
AllValidators.YardOptions に --plugin activesupport-concern を渡しているのも注目点です。ActiveSupportの Concern モジュールを多用するビューコンポーネント特有の構造を正しく解析させるため、既存の yard-activesupport-concern との連携を維持しています。
まとめ
yard-lint のCIへの組み込みにより、YARDドキュメントの品質劣化を自動的に防ぐ仕組みが整いました。段階的に無効化されているルールを順次有効化していくことで、プロジェクト全体のドキュメント品質を継続的に高めていく基盤が確立されています。