使用YARD记录顶级命名空间中的方法

Question

我使用YARD记录了一些Ruby代码，并且在获取我为顶级名称空间中的一些方法创建的YARD文档以在yardoc的HTML输出中显示时遇到了问题。

我的文档看起来与位于lib/ YARD /globals.rb中的yard gem的文档基本相同，只是增加了一个@api标记。我确实尝试过删除它，并在不带--api参数的情况下运行yardoc，但这对问题没有任何帮助。

这是一个示例：

#!/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

当我运行yardoc来生成HTML文档时，一切看起来都很正常：

% 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应用编程接口标记的方法列表。你可以在这里亲眼看到：

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 patchlevel 370) x86_64-linux上

Answer 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

使用这两个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标记。

Answer 2

正确的语法看起来是：

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

显然，要使--api选项正常工作，等号是必需的。我怀疑在其他情况下，名称pip-negotiate被用作解析文档的输入文件名。