Question

我使用YARD记录了一些Ruby代码，但是我无法获得YARD 我为顶级名称空间中的某些方法创建的文档，以显示在其中 yardoc的HTML输出。

我的文档与YARD gem的内容基本相同 lib / yard / globals.rb，添加了@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不包含我的任何文档。一切都好 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打破事情的评论使我处于正确的位置 track：虽然方法文档仍未显示在方法中如果我省略--api参数，它会显示在所有类的列表中地点（在“顶级命名空间”下）。这就是为什么我第一次没见它尝试省略--api参数。

我将尝试使用YARD格式化程序来保持方法列表不被显示，所以它并不会混淆我的用户，因为它让我感到困惑，并尝试划分我的用户文档/重构我的代码，以便我不需要多个@api标记任何给定的文件。

Answer 2

正确的语法似乎是：

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

--api选项显然需要等号才能正常工作。我怀疑其他名称pip-negotiate被用作输入文件名来解析文档。

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

2 个答案: