Macros don't work consistently when generating docs

Question

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/

Answer 1

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:

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

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.