1

YARD を使用していくつかの Ruby コードを文書化しましたが、トップレベルの名前空間のいくつかのメソッド用に作成した YARD 文書を yardoc の HTML 出力に表示するのに問題があります。

私のドキュメントは、lib/yard/globals.rb にある YARD gem のものと本質的に同じように見えますが、@apiタグが追加されています。私はそれを削除しようとしましたがyardoc、パラメーターなしで実行しまし--apiたが、問題は解決しませんでした。

これは例です:

#!/usr/bin/ruby

# @group PIP Negotiation: Backend and helper methods
#
# Deserializes a topology graph in YAML format into the database.
#
# @api pip-negotiate
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database ID of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output channel of flerd-deserialize.rb(1)
# @return [Array] output Standard error channel of flerd-deserialize.rb(1)

def insert_graph(graph)
  return [ true, 1, ["1"], [""] ]  # Not the actual method body.
end

# @endgroup

yardocHTML ドキュメントを生成するために実行すると、最初はすべて問題ないように見えます。

% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'                  
Files:           1
Modules:         0 (    0 undocumented)
Classes:         0 (    0 undocumented)
Constants:       0 (    0 undocumented)
Methods:         1 (    0 undocumented)
 100.00% documented
%

ただし、生成された HTML には、私のドキュメントは含まれていません。pip-negotiate含まれているのは、 API タグを持つメソッドのリストだけです。ここで自分の目で確かめてください：

http://btw23.de/tmp/pip-negotiate/api/method_list.html

私が代わりに期待していたのは、トップレベルのメソッドに関する YARD 独自のドキュメントのようなものでした。

http://rubydoc.info/gems/yard/toplevel

私のyardoc呼び出しに欠けている特別な魔法はありますか？

私の yardoc バージョンは 0.8.6.2 で、Ruby 1.8.7 (2012-06-29 パッチレベル 370) [x86_64-linux] で動作します。

4

2 に答える 2

1

の有無は--api関係ないようです。等号の有無にかかわらず、この--apiオプションにより、メソッドのドキュメントが表示されなくなります。等号に関係なく、他の場合でも機能します。トップレベルの名前空間にない一連のインスタンス メソッドに関するドキュメントを区分化するために、私はこれを頻繁に使用してきました。私は今その理由を見つけたと信じています。

どうやら@apiタグは名前空間にやや敏感で、独特な方法です。次の例を検討してください。

#!/usr/bin/ruby

# @api pip-negotiate

class Foo

# Deserializes a topology graph in YAML format into the database.
#
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output of flerd-deserialize.rb(1)

def insert_graph(graph)
  return true, 1, ["1"], [""]  # Not the actual method body.
end

end

これら 2 つのyardoc呼び出しのいずれかを使用すると、メソッド ドキュメントが適切にレンダリングされinsert_graph()ます。

% yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb'
% yardoc -o pip-negotiate --api pip-negotiate '**/*.rb'

しかし、@apiタグをメソッドに移動すると、問題が発生します。

#!/usr/bin/ruby

class Foo

# Deserializes a topology graph in YAML format into the database.
#
# @param [String] graph A FleRD graph in YAML format
# @return [Boolean] status True if graph was deserialized successfully, False otherwise.
# @return [Integer] gl_id The database of the deserialized GraphLabel (nil if deserialization failed).
# @return [Array] output Standard output of flerd-deserialize.rb(1)
# @api pip-negotiate

def insert_graph(graph)
  return true, 1, ["1"], [""]  # Not the actual method body.
end

end

呼び出しに関係なくyardoc、メソッドのドキュメントは無視されますが、メソッドはリストされます。私の仮説は、YARD のソースから検証するための予備のサイクルがないため @api、最も外側のタグ付け可能な名前空間 (この例では Foo クラス) からタグの切れ目のないチェーンが必要であるということです。そして、これまでのところ、最上位の名前空間にタグを付ける方法を見つけていませんが、それは役に立ちます.

そうは言っても、物事を壊すことに関するコメント--apiは私を正しい軌道に乗せました.パラメーターを省略した場合、メソッドのドキュメントはメソッドリストに表示されませんが--api、すべての場所のクラスリストに表示されます(「最上位の名前空間")。--apiそのため、最初にパラメーターを省略しようとしたときに、それがわかりませんでした。

メソッド リストが表示されないように YARD フォーマッタを使用して、ユーザーが混乱しないようにします。@api特定のファイルのタグ。

于 2013-10-01T11:02:57.937 に答える
0

正しい構文は次のようです。

yardoc -o pip-negotiate --api=pip-negotiate '**/*.rb'

--apiオプションが正しく機能するには、明らかに等号が必要です。pip-negotiateそれ以外の場合、名前はドキュメントを解析するための入力ファイル名として使用されていたと思われます。

于 2013-09-30T15:53:50.787 に答える