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

2022/04/19に公開

yard とは

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

なぜこれを導入したいか

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

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

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

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

yard の書き方

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

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

# 2つの文字列を連結する
#
# @param str1 [String] 1つ目の文字列
# @param str2 [String] 2つ目の文字列
# @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 が読み取ってくれる(インデントを1段深くする)
  • @yield ブロック引数について
  • @yieldparam ブロックパラメーターについて
  • @yieldreturn ブロックの返り値について

全部のリスト
https://rubydoc.info/gems/yard/file/docs/Tags.md#List_of_Available_Tags

Discussion