How to make Yard `@macro`s apply to multiple files

Question

If I have in one file the following:

module Something
  class Resource
    # Defines a new property
    # @param [String] name the property name
    # @param [Class] type the property's type
    # @macro [attach] property
    #   @return [$2] the $1 property
    def self.property(name, type) end
  end

  class Post < Resource
    property :title, String
    property :view_count, Integer
  end
end

The methods property defined with get documented properly. However, if I have in separate files these definitions the documentation is not generated properly, such as in the case as follows:

file0.rb:

require 'file1.rb'
require 'file2.rb'

file1.rb:

module Something
  class Resource
    # Defines a new property
    # @param [String] name the property name
    # @param [Class] type the property's type
    # @macro [attach] property
    #   @return [$2] the $1 property
    def self.property(name, type) end
  end
end

file2.rb:

module Something
  class Post < Resource
    property :title, String
    property :view_count, Integer
  end
end

When in separate files the Yard macros do not carry over when the documentation is generated. How does one enable this?

Answer 1

YARD doesn't follow require calls, and it is also a single pass parser, which means parse order matters. Basically, the file that defines the macros has to be parsed prior to the file that uses it. Presumably, your files aren't actually named 'file1.rb' and 'file2.rb', otherwise the default glob ordering would probably work in your favour.

To deal with multiple files, just ensure that YARD is parsing your "file1.rb" first. You can do this by putting it at the front of your glob, like so:

$ yard doc lib/path/to/file1.rb lib/**/*.rb

("But it will list 'file1.rb' twice," you say? Don't worry about uniqifying the list, YARD will do that for you)