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

当我运行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-negotiateAPI 标签的方法列表。您可以在这里亲自查看：

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]

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

使用这两个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 回答