【Rails】YARDOCについて

使い方

① Gemをインストールする

ターミナル

$ gem install yard

② YARDの規則に従って、メソッド上部にコメントを記載

yard_sample.rb

# サンプルメソッドです
#
# @param [Hash] options オプション
# @option options [Boolean] :busy 忙しいかどうかを設定 
# @return [Boolean] 成功：true 失敗：false
# @example
#  create_qiita_about_yard(options: { busy: true })
# @note 詳細は{https://qiita.com/ Qiita}を参照
# @see https://qiita.com/
def yard_sample_method(options: {})
  raise '忙しいすぎて勉強会の資料を作成できませんでした'if options[:busy]
  return true
rescue => e
  p e
  return false
end

③ 反映するコマンドを実行

ターミナル

$ yardoc yard_sample.rb

④ ブラウザ上でYARDを確認する

◆ 方法①
app/doc配下のindex.htmlファイルをブラウザで開く

◆ 方法②
YARD用のローカルサーバーを立ち上げる

ターミナル

$ yard server

http://localhost:8808 にアクセスする

タグ一覧

よく使うタグ

@param：メソッドの引数を説明
@option：メソッドのハッシュ引数を説明
@return：メソッドの返り値を説明
@raise：メソッドの例外クラスの説明
@example：メソッドの使用例を説明(インデントをずらさないとコード変換されないので注意)
@note：メソッドを使用する際の注意点やその他共有事項を記載する(「{}」で囲むことでリンクになる)
@see：URLや他のオブジェクトを書くとリンクになる

※おまけ：ファイルの大外にコメントを書くことで、「Overview」としてYARDに反映される

その他のタグ

@abstract：抽象クラス/モジュール/メソッドの説明
@api：オブジェクトに属するAPIの説明(yardoc --queryで実行した場合のみ出力)
@author：作者情報
@deprecated：非推奨のクラスやメソッドであることを表す
@private：YARD出力時にオプションで出力しないようにできる(yardoc --no-private)
@since：メソッド・クラスが利用できるようになったバージョンを説明
@todo：TODOを記載出来る
@version：オブジェクトのバージョンを示す