YARDで拡張ライブラリのドキュメントを書くときはメソッドの定義のところで@overloadタグを書かなきゃダメという話

はじめに

まぁ表題のとおりなんですが、要は
「YARDで拡張ライブラリのドキュメントを書くときは、@overloadタグでメソッドシグニチャを書かないと正しくドキュメントが生成されないので注意しましょう」
という話です。

環境

何が起こったかというと

拡張ライブラリで、Hashを渡すメソッドのドキュメントをYARDでこんな感じで書いてたんですよ。

/*
 * @param [Hash] opts parameters
 * @option opts [Number] :arg1 argument 1
 * @option opts [Number] :arg2 argument 2
 */
VALUE rb_foo(VALUE self, VALUE opts) {
  return Qnil;
}

で、

$ yardoc foo.c

とかやって作成したドキュメントを意気揚々と開いたわけですよ。

そしたらなんと、@optionで指定した :arg1 と :arg2 のドキュメントが出てこないじゃないですか。

f:id:ser1zw:20120430181745p:image

で、どうしたかというと

YARDのリポジトリにIssue登録を投げてみたら、
「CのコードでYARDを使うときは@overloadタグでメソッドシグニチャとかパラメータの記述をしないとちゃんと認識できねーよ」
との回答を頂いたので、こんな感じに書きなおしてみました。

/*
 * @overload foo(opts)
 *   @param [Hash] opts parameters
 *   @option opts [Number] :arg1 argument 1
 *   @option opts [Number] :arg2 argument 2
 */
VALUE rb_foo(VALUE self, VALUE opts) {
  return Qnil;
}

そしたらちゃんと@optionタグで指定した :arg1 と :arg2 の内容が表示されてました。

f:id:ser1zw:20120430181912p:image

まとめ

というわけで、YARDを拡張ライブラリで使う場合は@overloadタグをつけましょうね!というお話でした。