コードのドキュメント化

YARD タグの作成と修正

ここでは、いくつかのパラメーターをとるメソッドを文書化する方法を示します。この場合、メソッドは 2 つの引数を取り、これらの値の積を返します。

YARD タグを使用してこのメソッドにアノテーションを付け、誤ったタグを修正する方法について説明します。

コードインサイトのための YARD

RubyMine は、さまざまなコードインサイト機能に YARD 型のアノテーションを利用します。たとえば、オブジェクト型の決定、コード補完で取得したオブジェクト型の使用、メソッドのパラメーター情報の表示などです。いくつかの例を見てみましょう。

型情報を表示

RubyMine は、@return、@param、@yieldparam などの YARD タグを使用して、オブジェクトの型を判別します。

RubyMine は、指定されたタイプに対応する完了結果を提案することに注意してください。

戻り値 / パラメーター型の不一致

RubyMine は、メソッドの実際の戻り値とパラメーターの型が、@return および @param アノテーションを使用して提供された対応する型と一致するかどうかを確認できます。例: メソッドの戻り型が @return 型と一致しない場合、エディターは警告を表示します。

これらの警告は、不一致のパラメーター型および不一致の戻り型インスペクションを使用して管理できます。

パラメーター情報

RubyMine は @overload タグを理解し、パラメーター情報を表示するときに宣言されたすべてのオーバーロードを提案します。

@type タグ

標準の YARD および RDoc タグの他に、RubyMine は @type タグを処理して、可変型に関する情報を受け取ることができます。例: ローカル変数（変数名あり / なし）とブロックパラメーターにこのタグを使用できます:

• ローカル変数

  # @type [Integer] customer_id = 1 # @type [String] customer_name customer_name = "Andrew Fuller"

• ブロックパラメーター

  # @type [Integer] number [1, 2, 3].each do |number| puts "#{number}" end

YARD/RDoc コメントをレンダリングする

RubyMine を使用すると、YARD/RDoc コメントをエディターでレンダリングできます。レンダリングされたコメントは読みやすく、追加のタグでコードがオーバーロードになることはありません。リンクをクリックして、参照されている Web ページに移動したり、参照されているトピックのクイックドキュメントを表示したりできます。

RubyMine は YARD マクロ拡張も認識し、一般的なコーディング支援を提供します。マクロをレンダリングするとき、RubyMine はその参照の代わりにマクロデータを表示します。これには、マクロデータで使用される変数置換 ($1、$2 など) が含まれます。