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?
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:
("But it will list 'file1.rb' twice," you say? Don't worry about uniqifying the list, YARD will do that for you)