Rails/Rubyドキュメントをキレイに生成するYARD、早見表付き！

RubyやRailsのドキュメントを生成するGem YARDをご存じですか？ドキュメント生成GemではrDocが不動の一番すが、その後ろで猛追しているYARDというGemがあります。今回はこのGemの紹介です。

(02/16 23:30) Ruby 2.1で動作確認しつつリニュアール

🏀 Gemのイントロ

YARDはRubyのドキュメント生成rDocの次世代を期待されているGemです。
Ruby/Railsのコード内にYARDの書式でコメントを書くと、メソッドや引数、戻り値などの解説をうまく表示してくれます。

まずGemをインストールします。

gem install yard

次にプログラムソースにYARD形式のコメントを書いていきます。今回はファイル名hoge.rbのコードを作成していきます。

require 'date'

# 日本語形式の日付に変換
# @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

today = Date::today
puts convert_jp_date(today)

コーディングが完了したら、ドキュメントに変換。

yardoc hoge.rb

結果がこちら。

fpu_tmp_1354409713.093_342dc9

コードのコメントに規約を持たせれば、メンテナーンス性/可読性を高められますよね！

🐞 YARDドキュメント用のサーバ

YARDドキュメント用のサーバをhttp://localhost:8808で立ち上げる場合は次のコマンとをターミナルで実行する

yard server

🐰 YARDよく使うタグ一覧

(データ/型/名前/説明の書き方)
# @タグ [型] <名前> <説明>

(例)
# @param  [Array]  arr表示したい配列
# @return [String] 空白を除去した文字列

@params   メソッドに渡す引数の説明
@raise    メソッドで発生しえる例外クラスの説明
@return   メソッドの返り値の説明

@option メソッドに渡すオプションハッシュ引数の説明

# @param       [ハッシュ] opts the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from ('nobody') From address
# @option opts [String] :to Recipient email
# @option opts [String] :body ('') The email's body
def send_email(opts = {}) end

@overload 複数の引数のパターンがある場合にif文っぽく使う

# @overload set(key, value)
#   Sets a value on key
#   @param [Symbol] key describe key param
#   @param [Object] value describe value param
# @overload set(value)
#   Sets a value on the default key +:foo+
#   @param [Object] value describe value param
def set(*args) end

@example 直下の説明がサンプルコードであることを示す

# @example Reverse a String
#   "mystring".reverse #=> "gnirtsym"
def reverse; end

@see URLや他のオブジェクトを書くとリンクになる

# Synchronizes system time using NTP.
# @see http://ntp.org/documentation.html NTP Documentation
# @see NTPHelperMethods
class NTPUpdater; end

@note オブジェクトを使うときに注意して欲しい点を説明

# @note This method should only be used in outer space.
def eject; end

(中括弧)
{xxx} => リンクとみなす

(例)
# 詳細は、{http://rubydoc.info/docs/yard/0.7.2/file/docs/Tags.md Yardのタグ説明} を参照

🗻 YARDその他タグ一覧

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

@yield ブロックの説明。注意点としては、[]の中が引数となっていること。

# For a block {|a,b,c| ... }
# @yield [a, b, c] Gives 3 random numbers to the block
def provide3values(&block) yield(42, 42, 42) end

@yieldparam yieldのパラメータの説明

# @yieldparam [String] name the name that is yielded
def with_name(name) yield(name) end

@yieldreturn yieldの戻り値の説明

# @yieldreturn [Fixnum] the number to add 5 to.
def add5_block(&block) 5 + yield end

😼 公式リファレンス

実際は上以外にもタグがありますが、力尽きました！　ですので、詳細は公式リファレンスをw

Tags Overview

🎂 参考リンク

Ruby の YARD（Yardoc）の @ タグ

[ruby]rdocは捨て去られてYARDになった[gem]

🏈 変更来歴

(12/12/02) 新規作成

(14/02/16 23:30) Ruby 2.1で動作確認しつつリニュアール

🖥 VULTRおすすめ

「VULTR」はVPSサーバのサービスです。日本にリージョンがあり、最安は512MBで2.5ドル/月($0.004/時間)で借りることができます。4GBメモリでも月20ドルです。最近はVULTRのヘビーユーザーになので、「ここ」から会員登録してもらえるとサービス開発が捗ります！

酒と泪とRubyとRailsと