Rubyで定義したメソッドの使用例をYARD用のドキュメントとして書く方法 - 2013-09-19 - ククログ

はじめに YARDというRuby用のドキュメンテーションツールがあります。APIのドキュメントの記述方法は大きく2種類ありますが、YARDはコードにコメントとしてドキュメントを埋め込む形式を採用しています。専用の記法を使って構造化された読みやすいドキュメントを書けることが類似ツールであるRDocとの大きな違いです。 今回は「Rubyで定義したメソッドの使用例を示す」ドキュメントのYARD流の書き方を紹介します。 なぜ使用例の書き方を説明するかというと、使用例を1つ示すだけで使い方をぐっとわかりやすく説明することができるからです。もちろん、引数や戻り値などメソッドについての情報も必要ですが、それらは断片的な情報なため、そこから全体像をイメージするにはもうひとステップ必要になります。一方、使用例は詳細を示すことには不向きですが、どんな状況で使うのか、どのように準備して使うのかといった前後関係も

[tuto0621]

@exampleタグの使い方、最初に引数や戻り値じゃなくて実例をおく、というのはなるほど

[harabu]

かっこいい