生成文档时宏不能一致地工作
我在 YARD 文档工具中使用宏，在某些文件上它们可以工作，有些则不能。
例如，我在我的源文件之一中定义了一个宏。
# @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/
I am using macros in the YARD doc tool and on some files they work and some they don't.
For example, I define a macro in one of my source files.
# @macro [new] my_macro
# @param [String] my_string it's a string!
#
def method(my_string)
#do stuff
end
Then in other files/classes I have:
#@macro my_macro
def a_method(my_string)
#do stuff
end
When I run the doc generator, the macro will work for many of the files but not all. My guess is that the doc generator isn't seeing the macro before generating the docs that failed. Once it reaches the macro, it works for every file after that. But that is a guess.
Is there a way to ensure that the macro works for every file? I suspect there is a disconnect between how I think macros work in YARD and how they actually do work.
P.S. For those that don't know what YARD is, you should check it out. It essentially does what rDoc does, but much much better. http://yardoc.org/
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
它确实取决于 YARD 处理源文件的顺序，当前唯一的解决方案是通过将文件列表传递给yardoc来手动设置该顺序，如下所示：
这将首先处理定义宏的文件，然后处理所有其他文件。请注意引号，YARD 有自己的通配符，因此可以使用例如
**（递归通配符），是的，如果您有循环“依赖项”，这将不起作用，即两个文件使用彼此的宏。
根据 YARD 开发人员的说法，使用两次传递来首先获取所有宏会对性能造成太大影响，因此不要指望这种情况会很快改变。
编辑：这个想法的扩展是有一个专门用于定义宏的文件，因为它们的定义没有理由必须与方法的实现位于同一文件中。
It indeed depends on the order in which YARD is processing your source files, and the currently only solution is to manually set that order by passing a list of files to yardoc, like following:
This will first process the file that defines macros, then all other files. Please note the quotation marks, YARD does its own globbing, so that e.g.
**will be possible to use (recursive glob)And yes, this won't work if you have a circular "dependency", i.e. two files using each others' macros.
According to the YARD developer, using two passes to first get all macros would have a too heavy imposition on performance, so don't expect this to change any time soon.
Edit: An extension of this idea is to have a file dedicated to defining macros, as there is no reason that their definition has to be in the same file as the implementation of your methods.