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

Question

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

我的文档看起来与 YARD gem 自己的文档基本相同 lib/yard/globals.rb，添加了@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 不包含我的任何文档。全部 contains 是带有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 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 被用作输入文件名来解析文档。