コメントでRDoc/Yard生成

• RDocとYardの概要
• コメントから生成する方法
• HTMLドキュメントとAPI仕様書
• 記述ルールと可読性の向上

RDocとYardの概要

Ruby実践においてドキュメントはコードの可読性を大幅に向上させる重要な要素です。RDocはRuby標準のドキュメント生成ツールで、コメントからHTMLドキュメントを自動生成します。一方、Yardはより高度な機能を備えたオープンソースツールで、型情報やテストコードの統合、カスタムタグのサポートなどが特徴です。両者とも「コメントから生成」という共通点を持ち、API仕様書を簡単に作成できます。

コメントから生成する方法

ドキュメントを生成する際は、コードに以下のような記述ルールを守ることが推奨されます。

• クラスやメソッドの先頭に##で始まるコメントを記述
• 引数や戻り値の型を@param、@returnタグで明示
• 例外を@raiseで記載し、発生条件を説明

例として、Yardでのコメントは次のようになります。

# 例: Userクラス
# @param name [String] ユーザー名
# @param age [Integer] 年齢
# @return [User] 新しいUserインスタンス
def initialize(name, age)
  @name = name
  @age = age
end

このコメントをYardに渡すと、HTMLドキュメントが自動生成され、API仕様書として利用できます。

HTMLドキュメントとAPI仕様書

生成されたHTMLドキュメントは、開発者だけでなく、プロダクトマネージャーやテスターにも有用です。API仕様書として利用する場合、以下のポイントに注意します。

1. エンドポイントごとにメソッド名とURLを明示
2. リクエストパラメータとレスポンス構造をJSON例で示す
3. 認証情報やエラーレスポンスのコードを一覧化

Yardのyardocコマンドを実行すると、docディレクトリにHTMLファイルが生成されます。これを社内WikiやGitHub Pagesに公開すれば、最新のAPI仕様書を常に参照できます。

記述ルールと可読性の向上

ドキュメントの可読性を高めるためには、以下の記述ルールを徹底しましょう。

• コメントは必ず日本語と英語の両方で記載（多国籍チーム向け）
• コードブロックはインデントを揃え、読みやすく
• 同一クラス内でメソッドを論理的にグループ化し、順序を統一

さらに、Yardのyardoc --format htmlオプションでカスタムテンプレートを使用すると、企業ロゴやカラーを反映したドキュメントを作成できます。こうした工夫は、ドキュメントを読む人の負担を減らし、開発サイクルをスムーズにします。

この記事はAIによって作成されました。