YARD の設定 - 不定期刊 Rails App を作る(8)

RailsApp Rails Yard 2018年 11月 14日

昨日までに記載したメソッドの上には定型的なコメントを書いていた． これは，YARD と呼ばれる Documentation Tool のためのコメントである． あまりサンプルがが大きくなる前に紹介しておく． ちなみに，YARD は Yay! A Ruby Documentation Tool らしい．他のものと同じで Yet another XXX 系かと思っていたが違っていた．

YARD のインストール

1. 例にもれず，Gemfile の development に追加する．

group :development do
  gem 'yard'
  (中略)
end

2. bundle する(2行目以降は結果: 追加分のみ)

$ bundle
Fetching yard 0.9.16
Installing yard 0.9.16

3. yard を実行する(2行目以降は結果)

$ be yard
Files:           5
Modules:         1 (    1 undocumented)
Classes:         4 (    4 undocumented)
Constants:       0 (    0 undocumented)
Attributes:      0 (    0 undocumented)
Methods:        12 (    1 undocumented)
 64.71% documented

結果例

1. yard を実行すると，doc 以下にドキュメントが生成される．以下は doc 以下のファイル一覧を示したものである．

$ ls -R doc
ApplicationController.html file.README.html
ApplicationHelper.html     file_list.html
ApplicationJob.html        frames.html
ApplicationRecord.html     index.html
PagesController.html       js
_index.html                method_list.html
class_list.html            top-level-namespace.html
css

doc/css:
common.css    full_list.css style.css

doc/js:
app.js       full_list.js jquery.js

2. この中の index.html を開くと README が表示される．
3. デフォルトで左側には Class list が表示されているが，Methods や Files をクリックすると，それぞれメソッド一覧やファイル一覧が表示される．
4. 今回 ApplicationHelper にメソッドを記録したので，ここにはメソッドの説明が記載されている．以下は Instance Method Summary 部分のスクリーンショットである．

5. Summary の部分でメソッド名をクリックすると，Instance Method Details の部分に飛ぶ．コメント部分で @param とした部分が Parameters 隣，@return と書いた部分が Returns に対応していることがわかる．

6. View source の部分をクリックすると，該当するメソッドのソースプログラムを見ることができる．

スクリーンショットで場所を取ってしまったので今日はここまで