yard でドキュメントを生成し確認する

yard とは

Ruby で使える、ドキュメントの書式を提供し、ドキュメントを生成できるライブラリです。

• https://github.com/lsegal/yard

なぜこれを導入したいか

メソッドに説明を書く時に決まった書式があると書きやすいため。
また、yard を書いておくとIDEがいい感じに補完してくれたりする。

yard でドキュメントを生成する

yardoc コマンドで yard のドキュメントを生成できる。html をブラウザで開けば閲覧可能。

$ docker exec -it backend bundle exec yardoc
$ open doc/index.html

yard の書き方

• １行目に説明コメントを書く
• ２行目は空けて、３行目以降にパラメーターと返り値を書く
  • @param で引数を定義する。 @param 引数名 [型] 説明 という順番で書く
  • @return で返り値を定義する。 @return [型] 説明 という順番で書く

引数名と型は逆の順番でも問題ないが、この順番だと引数名と説明が [型] で区切られるので分かりやすい。

# ２つの文字列を連結する
#
# @param str1 [String] １つ目の文字列
# @param str2 [String] ２つ目の文字列
# @return [String] 連結された文字列
def concat(str1, str2)
  str1 + str2
end

# 日本語形式の日付に変換
#
# @param date [Date] 日付
# @return [String] 日付を YYYY年MM月DD日 の形式にしたもの
# @return [nil] 引数が Date 型以外の場合は nil
def convert_jp_date(date)
  (date.class == Date) ? date.strftime('%Y年%m月%d日') : nil
end

これ以外にも色々な書き方があるが、最初はこれだけでも必要なものは書けると思う。

個人的によく使うやつ

• @raise 想定される例外（エラーハンドリングしてて中で明示的に例外を発生させてる時とか）
• @see 参照してほしいURLを書きたい時に
• @note 注意点とかを追加で書ける
• @todo TODOコメント
• @example この下にサンプルコードをコメントで書くと yard が読み取ってくれる（インデントを１段深くする）
• @yield ブロック引数について
• @yieldparam ブロックパラメーターについて
• @yieldreturn ブロックの返り値について

全部のリスト