問題タブ [yard]

私が取り組んでいるいくつかのプロジェクトのドキュメントを生成するためにYARDを使用しています。1 つは、他のプロジェクトで使用される多くの冗長な共有リソースをホストする gem を共同開発しています。

私が望むのは、最初のプロジェクトから宝石のクラスまたはメソッドへの参照がメイン プロジェクトのドキュメントに表示されることです。例えば

宝石

計画

SpecialWidget のドキュメントで、Widget#spin メソッドへの実際のリンクを生成したいと思います。

これはできますか？

基本的な Ruby メソッドの場合、パラメーターの YARD スタイル ドキュメントを次の形式で提供します。

Ruby 2.0 では、キーワード引数を使用できるようになりました。ただし、YARDのドキュメントに関しては、それにアプローチする方法がわかりません。

2 番目のシナリオでは、どのように文書化しexact_matchますか? このキーワードresults_per_pageを使い続けるべきですか、それとももっと良いものがありますか?@param

次のように、可変数の引数を取る関数があります。

すべての引数は同じ型 ( Symbol) であるため、現在、引数が 1 つしかないかのように関数を文書化して、複数の引数を取ることができると言っています。

このケースを処理する組み込みの方法はありますか?

次のように文書化された関数があります。

この結果が得られます:

私の問題は、関数がブロックを期待し、値を返すとドキュメントに記載されていることです。実際には、ブロックはオプションです。ブロックが提供されている場合は、結果ごとに呼び出され、関数は何も返しません ( nil)。ブロックが指定されていない場合、結果は配列で返されます。

ドキュメントでこれを明確にするにはどうすればよいですか? おすすめの方法はありますか？

ユーザーが見つからない場合は User または nil を返す関数があります。次のようになります。

私の質問は、それが見つからない場合に User または nil を返すことをどのように文書化するのですか?

pryRSpecを要求しspec_helper.rbてスペックを実行すると、大量の警告が表示されます。これらを取り除くにはどうすればよいですか？

Yard のドキュメントと例を見ていると、エクスクラメーション マークの付いたタグがいくつか見つかりました。

感嘆符の有無にかかわらず動作する例を見つけましたが、違いを見つけることができませんでし@!some-tagた@some-tag。

たとえば、このコードは と の両方について同じドキュメントを生成しますattr。attr2

一方で、いくつかの 例では、感嘆符の重要性に下線が引かれているため、何かを行うことになっていますが、その使用法に関するドキュメントは見つかりません。

@!メソッドの例

Rails モデルのこれらのコメントは両方とも、新しいメソッドを生成します

ヤード出力: