⛳
yard でドキュメントを生成し確認する
yard とは
Ruby で使える、ドキュメントの書式を提供し、ドキュメントを生成できるライブラリです。
なぜこれを導入したいか
メソッドに説明を書く時に決まった書式があると書きやすいため。
また、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注意点とかを追加で書ける -
@todoTODOコメント -
@exampleこの下にサンプルコードをコメントで書くと yard が読み取ってくれる（インデントを１段深くする） -
@yieldブロック引数について -
@yieldparamブロックパラメーターについて -
@yieldreturnブロックの返り値について
全部のリスト
Discussion