【Rails】RDocを導入して自動ドキュメント生成をする方法【その1】

｜ 2014/11/01 ｜カテゴリー：開発｜タグ：Rails, RDoc, Ruby, 開発

RDocとは?

RDocとは、Rubyで書かれたソースコードからドキュメントを自動生成するRuby本体に付属する標準ライブラリの1つです。
RDocはRuby Documentation Systemの略でRubyソースコードを解析し、クラス、モジュール、メソッドの定義を抜き出し、includeやrequireに関して解釈します。
そしてこれらの内容とその直前に書かれたコメントを併合し、HTMLドキュメントを出力します。

インストールの方法

下記のコマンドでversionの確認します。

rdoc --version

最新versionを入れる場合

gem install rdoc

versionを指定してインストールする場合

gem install rdoc --version 4.0.1

ドキュメント作成コマンド

【新規】新規の場合は doc ディレクトリの中で下記コマンドを実行

rake doc:app

【更新】現在あるドキュメントを強制的に上書きする場合は下記コマンドを実行

rake doc:reapp

【削除】アプリのドキュメントファイルを削除する場合は下記コマンドを実行

rake doc:clobber_app

コメントの挿入箇所について

コメントの挿入箇所についてはプロダクトによると思いますが、私の場合は以下の場所に挿入します。

・ファイルヘッダ(ファイルの先頭)
・クラス/モジュールの直前
・メソッドの直前
・定数宣言の直前
・クラス変数宣言の直前

○ 良い例

#encoding: utf-8
# クラスの説明
#  Author:: 作成者
#  Date::   作った日

class HogeController < ApplicationController
#******************************

  # hogeの説明
  #  Param::  パラメータの説明
  #  Return:: 戻り値の説明
  def index($arg1, $arg2)

× 悪い例

#encoding: utf-8
# クラスの説明
#  Author:: 作成者
#  Date::   作った日
class HogeController < ApplicationController
#******************************
  # hogeの説明
  #  Param::  パラメータの説明
  #  Return:: 戻り値の説明
  def index($arg1, $arg2)

悪い例だと出力されたドキュメントがおかしなことになって出力されます。