Question

我在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

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

有没有办法确保宏适用于每个文件？我怀疑我认为宏如何在YARD中工作以及它们实际上如何工作之间存在脱节。

P.S。对于那些不知道YARD是什么的人，你应该看看。它基本上做了rDoc的功能，但要好得多。 http://yardoc.org/

Answer 1

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

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

这将首先处理定义宏的文件，然后处理所有其他文件。请注意引号，YARD有自己的整体，所以例如**将可以使用（递归glob）

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

根据YARD开发人员的说法，使用两遍来获得所有宏会对性能产生太大的影响，所以不要指望它会很快改变。

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