
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)
悪い例だと出力されたドキュメントがおかしなことになって出力されます。
記事を書くのが疲れたので・・
今回はRDocのインストールやコマンド、挿入場所について書きましたが次に書き方とオプションについてまとめたいと思います。
【Rails】RDocを導入して自動ドキュメント生成をする方法【その2】