3

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/

juan2raid
  • 1,606
  • 1
  • 18
  • 29

1 Answers1

4

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.

Dominik Honnef
  • 17,937
  • 7
  • 41
  • 43
  • Thanks. Would you know the syntax for the single file of defined macros? YARD doesn't appear to pick the macros up unless the macro is associated with a class/module/method when it is defined. – juan2raid Nov 09 '11 at 01:29
  • The work-around is just to have the macro file contain a dummy method for every defined macro, but it looks a bit silly. – juan2raid Nov 09 '11 at 01:30
  • Yeah, there doesn't seem to be any other way right now. YARD will go through some major changes regarding its (macro) architecture in a future release though, so that might open up new possibilities, including a DSL for defining macros outside of the actual source code – Dominik Honnef Nov 11 '11 at 13:29
  • 1
    YARD 0.8 will allow you to define macros inside of freeform comments. You could place those freeform comments in the root .rb file of your project and define all your system-wide macros like that. Note: YARD sorts the glob by path length so as to ensure that parent directories are processed before children. The lib/mylib.rb file is always processed first. – Loren Segal Apr 27 '12 at 06:47