3

我在 YARD doc 工具中使用宏，并且在某些文件上它们可以工作，而有些则不能。

例如，我在我的一个源文件中定义了一个宏。

# @macro [new] my_macro
# @param [String] my_string it's a string!
#
def method(my_string)
  #do stuff
end

然后在其他文件/类中我有：

#@macro my_macro
def a_method(my_string)
  #do stuff
end

当我运行文档生成器时，宏将适用于许多文件，但不是全部。我的猜测是文档生成器在生成失败的文档之前没有看到宏。一旦到达宏，它就适用于之后的每个文件。但这是一个猜测。

有没有办法确保宏适用于每个文件？我怀疑我认为宏在 YARD 中的工作方式与它们的实际工作方式之间存在脱节。

PS 对于那些不知道 YARD 是什么的人，你应该检查一下。它基本上完成了 rDoc 所做的工作，但要好得多。http://yardoc.org/

4

1 回答 1

4

它确实取决于 YARD 处理源文件的顺序，目前唯一的解决方案是通过将文件列表传递给 yardoc 来手动设置该顺序，如下所示：

yardoc "lib/foo_that_defines_buncha_macros.rb" "lib/**/*.rb"

这将首先处理定义宏的文件，然后处理所有其他文件。请注意引号，YARD 进行自己的 glob，因此**可以使用 eg (recursive glob)

是的，如果你有一个循环的“依赖”，这将不起作用，即两个文件使用彼此的宏。

根据 YARD 开发人员的说法，使用两次传递首先获取所有宏会对性能造成太大影响，因此不要指望这种情况会很快改变。

编辑：这个想法的扩展是有一个专用于定义宏的文件，因为没有理由将它们的定义与方法的实现放在同一个文件中。

于 2011-11-07T02:38:52.530 回答