Rubyには、ソースコードとそのコメントからドキュメントを自動で作成してくれる便利なツールがあるますが、多くのRubyのプログラマーが注目しているツールがYARDです。
Rubyは短い記述で読みやすいプログラムが書けるプログラム言語ですが、ドキュメントが不要ということはありません。独自に作ったクラスやメソッドの仕様など、後からプログラムを修正する際にはドキュメントは必須です。
今回はRuby用のドキュメント自動生成ツールに興味のある方に、RubyGemsから入手できるYARDの機能と使い方を紹介します。
Rubyでコードのドキュメントを作るには
今回紹介するYARDは、RubyのプログラムのソースコードからHTML形式のドキュメントを自動作成するツールです。YARDについて解説する前に、ドキュメントを生成する際の課題と、自動生成の仕組みについて紹介します。
ソースコードだけでは不十分
Rubyをはじめとするプログラム言語は、言語と言われるとおり、それを読めばシステムがどのように動作するか理解できます。しかし、プログラムによってはソースコードがかなり大きく、ソースコードだけでシステム全体の動作を理解するのは大変です。
そこで使われているクラスの仕様や扱うデータモデル、変数に格納される内容などを解説したドキュメントを作成して、プログラムを作成したり修正する際に利用します。
さらにプログラムを作成したらそれで終わりではありません。機能の追加や不具合の修正などのメンテナンス作業が発生します。そのような作業で別の担当者がプログラムを修正するためにドキュメントが必要です。
ドキュメント作成の課題
先ほど説明したようにプログラムのソースコードを作成したら、そのドキュメントも必要です。しかし限れた時間でプログラムを作成し、さらにドキュメントも作成するのは面倒です。
かつてはプログラムを作成したエンジニアがドキュメントの作成も担当していました。しかいプログラム作成時間が足りないケースではドキュメントを書く時間が取れず、まともなドキュメントが無いケースもあり、そのようなケースではその後のメンテナンスが大変でした。
そこで今使われている方法は、ソースコードの内容とそこに書かれたコメントから、ドキュメントを自動で生成するツールの利用です。これならプログラムを書いた後に、時間をかけずにドキュメントを作成できます。
Rubyで使えるドキュメント生成ツール
Rubyには標準でRDocというドキュメントを自動生成するツールが付属しています。しかし、RDocは使いやすいとはいえません。そこでより使いやすいドキュメント自動生成ツールとして作られたのがYARDです。
もし、Ruby on Railsのプログラムコードからドキュメントを自動生成して活用しようと考えているようなら、ぜひ、YARDの利用を検討してください。
YARDとは
今回紹介するYARDは、Rubyのプログラムのソースコードとそこに記載されたコメントからHTML形式のドキュメントを自動的に生成するツールです。そしてYARDは、RubyGemsからインストールすることで利用できます。
次からYARDの特徴をRubyに標準で付属しているRDocと比較しながら解説します。
ドキュメント生成ツールの機能
YRADとRDocは、どちらもRUbyのソースコードを解析し、クラス、モジュール、メソッドの定義を抜き出し、その前後に書かれたコメントと組み合わせて、HTML形式のドキュメントを生成します。
Rubyはオブジェクト指向プログラムであり、プログラムの中で使われる要素は全て何らかのクラスに属しています。そのためプログラムの中の要素のことを知るには、それがどのクラスに定義され、どのように定義されているか知らなければなりません。YARDやRDocが生成するドキュメントは、Rubyのソースコードを読む際に必須の情報を提供してくれます。
YARDはRubyGemからインストールできる
先ほど紹介したようにRubyのプログラムを編集するドキュメントが必要ですが、それを作るRDocはRubyに標準で付いているツールのため、インストールしなくても使えます。一方、YARDはRubyGemで提供されているツールです。そのためYARDを使うには、gemコマンドなどでインストールしてください。
YARDをインストールするgemコマンドの例
$ gem install yard
YARDをインストールできたら、yardocコマンドが実行できるかチェックしてみてください。下記のコマンドを実行してインストールしたyardのバージョンが表示されたら正常です。
yardocコマンドのバージョンを表示するコマンド
$ yardoc --version
YARDとRDocの違いとは
先ほど紹介したようにRDocとYARDはどちらもソースコードからドキュメントを作成しますが、ソースコードに書かれたコメントを利用する機能が違います。
RDocとYARDはどちらもコメントに属性を記述し、より見やすいドキュメントを作ることが可能です。ただしYARDは機能が多く、より見やすいドキュメントを記述できます。ただし、専用のマークアップ言語を使うことから、YARDを使いこなすには、そのマークアップ言語を覚えて、見やすく書くスキルの習得が必要です。
yardocコマンドの使い方
先ほど紹介したようにYARDは、RubyのプログラムのソースコードからHTML形式のドキュメントを自動的に生成するツールです。次からその使い方を紹介します。
ドキュメントの作り方
YARDでRubyのプログラムのドキュメントを生成するには、次のようにyardocコマンドにRubyのプログラムのソースファイルを指定します。
YARDの実行例
$ yardoc sample.rb
yardocコマンドを実行すると、実行したディレクトリにdocが作られて、その下にHTML形式のドキュメントが作成されます。なお、対象のソースファイルにクラスが定義されていれば、そのクラス名のファイルが作られます。
yardocコマンド実行時に作成されるファイル
(クラス名).html _index.html class_list.html file_list.html frames.html index.html method_list.html top-level-namespace.html css/ js/
ドキュメントの例
YARDを使って作成したドキュメントの例を次に紹介します。
Rubyのプログラムの例
class Oneclass
# テスト用のクラス
# @param [String] val1 処理開始時のメッセージ
# @param [String] val2 処理終了時のメッセージ
def initialize( val1, val2)
@val1 = val1
@val2 = val2
end
# 処理開始時
# @return [String] 処理開始時のメッセージを返す
def do_start()
msg = @val1
end
# 処理終了時
# @return [String] 処理終了時のメッセージを返す
def do_end()
msg = @val2
end
end
上記のRubyのプログラムでは、「@param」と「@return」の2つのYARD形式のタグを使ったコメントを記載しています。そして、これらのタグは、yardocコマンドで生成したドキュメントにも記載されています。
よく使われるYARD形式のタグ
先ほどの例で紹介したようにyardocコマンドで生成したHTMLのドキュメントは、YARD形式のタグを追加することで、より読みやすくできます。
なお、YARD形式のタグは、コメントに「@」または「@!」で始まるタグ名を指定し、続いて型指定子リストを[]の中に指定し、その次にドキュメントに反映させるコメントを記載します。
YARD形式のタグの記述方法
# @タグ名 [型指定子リスト] ドキュメントに反映させるコメント
次によく使われるYARD形式のタグを紹介します。
@params メソッドに渡す引数の説明
@raise メソッドで発生しえる例外クラスの説明
@return メソッドの返り値の説明
@option メソッドに渡すオプションハッシュ引数の説明
@see URLや他のオブジェクトを書くとリンクになる
@note オブジェクトを使うときに注意して欲しい点を説明
まとめ
Rubyは短く読みやすいプログラムが書ける言語ですが、ドキュメントが不要という訳ではありません。しかしプログラムを書いて、さらにドキュメントも書くのは面倒です。
これまで紹介したように、yardocコマンドにRubyのソースファイルを指定して実行するとHTML形式のドキュメントを生成できます。さらに、コメントにYARD形式のタグを使って書いておくと、そのコメントをドキュメントに反映することが可能です。
Rubyのプログラムに対応するドキュメントを作成するなら、ぜひ、ドキュメントを自動生成できるYRADの利用を検討してください。
