Rubyのyardを使ってソースからドキュメントを生成する方法

19/01/20 15:48:35 19/05/05 17:53:54

Rubyのyardとは、ドキュメントを生成するための機能で、Gemの一種です。GemはRubyのライブラリのなかでも有名ですが、Ruby Gemsが公開しています。Gemというライブラリがあって、そのなかにyardというドキュメント生成機能がある、とざっくり捉えておけば良いかと思います。

ちなみに、yardと同じような機能を持つものにRDocというものがあるのですが、RDocの方が古いです。RDocは自由度が高くいろいろなドキュメントを作成できるのですが、その分かえってドキュメントの作り方に迷ったり、たとえばチームで開発していてドキュメントの形式にばらつきが発生する、といったことがありました。

yardの場合ドキュメントの形式が限られているため、使いやすいというメリットがあります。ドキュメントに自由度の高さを求める場合RDocの方が良いのですが、多くの場合ドキュメントは読みやすければそれで良いのでデフォルトの形式を決めてくれたらそれで良い、といった感じでしょう。

yardなら特に考えずに使ってもうまくHTMLドキュメントが生成されるので、利便性が高いです。

1 yardの使い方
2 yardでタグコメントを使う方法
3 yardでよく使うタグコメント
4 Rubyのフリーランス案件をチェック

yardの使い方

ライブラリの中身などの詳細よりも実際に使えることが重要なので、さっそくyardの具体的な使い方を解説しています。まずyardはGemの機能なので、最初にGemをインストールします。コマンドは以下のようになります。

gem install yard

これでGemのインストールができました。Gemをインストールすると、そのなかに含まれているyardはすぐに使用できます。yardの具体的な使用の流れとしては、以下のようになります。

対象ファイルを作成する（もともと存在する場合は作成しなくても良い）
↓
yardocコマンドで、対象のファイルを指定する
↓
そのファイルに含まれているクラス、メソッドについてのドキュメントが生成される

基本の流れは上記のようになります。コマンドでファイル指定するだけで、そのファイルのなかの基本情報をドキュメントとして出力することができるのです。

ただし、これだけだとクラス、メソッド、クラスの継承関係、ソースコードなどが閲覧できるにとどまります。そのクラス内でどのような処理が行われているのか、ソースコードの全体構造はどうなっているのか、ということまではわからないのです。

自分で確認する場合やプロジェクト内であらかじめ情報共有ができている場合上記の基本情報だけでわかるので問題ないのですが、基本情報だけでは中身を把握できない場合もあるでしょう。

そこで、タグコメントを使用するという方法があります。

yardでタグコメントを使う方法

タグコメントとは、yard専用のコメントです。どういうことかというと、ソースコードにタグコメントをあらかじめ記述しておけば、yardocコマンドでドキュメントを出力した際にタグコメントを表示してくれるのです。

たとえばクラスやメソッドに対してタグコメントを付けておけば、ドキュメントないではセットで表示されます。なので、タグコメントに書く内容としては「そのクラスは何のためにあるのか」「メソッドではどのような処理を行っているのか」といったことになります。

基本的には普段プログラミングしているときに書くコメントと同じような使い方ですが、それがドキュメントに反映されるということです。Rubyのコメントアウトには「#」「=begin～=end」「__END__」といった文法がありますが、このように普通にコメントアウトしてもyardocコマンドで出力したドキュメントには反映されません。

これを反映させるために、タグコメントを使用します。またタグコメントの記述方法は簡単で、「@～」というタグで、パラメータ/返り値/サンプルコードなどを記述できます。@が付いていると、yard側でタグコメントとして認識します。

ただしRubyの実行環境側ではソースコードのなかに普通に@が入っているとバグなので、コメントアウトして記述します。そうするとRubyの実行環境側ではコメントアウトされている@を読み飛ばし、yard側では@を認識する、という形にできます。

yardはRubyのコメントアウトに関係なくコードを読み込むので、Rubyでコメントアウトされていてもyardで認識しないということはありません。逆に言えば、あまりそのような使い方はしないかもしれませんがコメントアウトしているクラスやメソッドもyardではドキュメントに表示されます。

システム上使用しなくなったクラスやメソッドを一時コメントアウトしておくようなケースが稀にあるかもしれませんが、それでもyardでは読み込まれるので、yardコメントで使われていない機能だとすぐにわかるように何かしら@で書いておくと良いかもしれません。

yardでよく使うタグコメント

次に、yardでよく使うタグコメントを紹介します。すべて細かく見る必要はないですし、ましてや覚える必要もありません。よく使うタグコメントは勝手に覚えていくでしょう。

【データ/型/名前/説明の書き方】
# @タグ [型] <名前> <説明>

【例】
# @param [Array] arr表示したい配列
# @return [String] 空白を除去した文字列
@params メソッドに渡す引数の説明
@raise メソッドで発生しえる例外クラスの説明
@return メソッドの返り値の説明
@option メソッドに渡すオプションハッシュ引数の説明

# @param [ハッシュ] opts the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from (‘nobody’) From address
# @option opts [String] :to Recipient email
# @option opts [String] :body (”) The email’s body
def send_email(opts = {}) end
@overload 複数の引数のパターンがある場合にif文っぽく使う

# @overload set(key, value)
# Sets a value on key
# @param [Symbol] key describe key param
# @param [Object] value describe value param
# @overload set(value)
# Sets a value on the default key +:foo+
# @param [Object] value describe value param
def set(*args) end
@example 直下の説明がサンプルコードであることを示す

# @example Reverse a String
# “mystring”.reverse #=> “gnirtsym”
def reverse; end
@see URLや他のオブジェクトを書くとリンクになる

# Synchronizes system time using NTP.
# @see http://ntp.org/documentation.html NTP Documentation
# @see NTPHelperMethods
class NTPUpdater; end
@note オブジェクトを使うときに注意して欲しい点を説明

# @note This method should only be used in outer space.
def eject; end

Rubyのyardは以上のようになります。個人開発だとあまり使わないかと思いますが、チームで開発している際は利便性が高いです。自分が一メンバーとして参加する場合はルールに従ってドキュメント作成すれば良いですが、自分がリーダーの場合もあるでしょう。

自分がリーダーの場合みんなが他の人のコードをすぐに理解できるよう何らかの対策が必要ですが、yardでのドキュメント生成はその一例でもあります。ソースコードのコメントに加えてドキュメントを生成すればよりプログラムの管理も便利になるので、ぜひドキュメントにも目を向けてください。