📘 hkob-astro-notion-blog

これまではてなブログにて情報発信をしていましたが、令和5年3月22日より、こちらでの情報発信を始めました。2019年以前の古い記事は過去の Middleman 時代のものなので、情報が古いです。記録のためだけに残しています。
2018-11-14
Rails Yard

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

💡
この記事は Middleman 時代に書いた古いものです。記録のため、astro-notion-blog に移行していますが、あまり参考にしないでください。

昨日までに記載したメソッドの上には定型的なコメントを書いていた． これは，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 部分のスクリーンショットである．
    image block
  5. Summary の部分でメソッド名をクリックすると，Instance Method Details の部分に飛ぶ．コメント部分で @param とした部分が Parameters 隣，@return と書いた部分が Returns に対応していることがわかる．
    image block
  6. View source の部分をクリックすると，該当するメソッドのソースプログラムを見ることができる．
    image block

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

Rails Yard