Iterating Over the Registers of a Yardoc '@Macro'

Macros don't work consistently when generating docs

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.

Documenting def_delegators with Yardoc

After more experimentation I found that this worked quite well:

  # @!method size
  #   @see Array#size
  # @!method <<
  #   @see Array#<<
  # @!method blah
  #   @see Array#blah
  def_delegators :@xs, :size, :<<, :blah # …

There is quite possibly a way to do this in one or two lines, but compared to the work writing an extension I find this very acceptable.

---

Update:

I've just found this will link to the delegated methods' documentation better:

  # @!method size
  #   @return (see Array#size)

This would take the already documented return value from the Array#size method. I expect the other tags will do this too. It's still quite verbose, but acceptable.

How to automatically document Metaprogrammed attr_accessors using RDoc?

Define a Domain Specific Language (DSL) and use Yard Macro Expansion Variables.

Also see my other related questions:

• Iterating over the registers of a Yardoc @macro
• How to make Yard @macros apply to multiple files
• Dynamic documentation, using the return of method in the description of another YARD?
• Ruby DSLs and Dynamic Documentation?

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

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)

Documenting parameters for macro generated methods with YARD

You are correct that rspec uses this documentation and you can see that they specify using the defined macro

# @macro [attach] add_setting
#   @!attribute [rw] $1
#   @!method $1=(value)
# .....
# @macro add_setting
# Run examples over DRb (default: `false`). RSpec doesn't supply the DRb
# server, but you can use tools like spork.
add_setting :drb

If you notice the @macro add_setting declaration this tells yard when documenting this method use the add_setting macro. In this case $1 means drb so it will document the drb attribute. (not the individual getter/setter methods)

As you can see when they are documenting these methods they do not declare a data type because these types may differ for the different documented methods. Instead they specify the default in the description of the method.

Option 1 (not sure why it works)

Just define the getter and setter rather than using !@attribute declaration which would look like

class A
  # @!macro [attach] add_setting
  #   @!method $1
  #     @return [Object] the $1 of the a 
  #   @!method $1=(value)
  def self.add_setting(setting)
  end
  # @param value [String] Hexadecimal representation of color
  add_setting :color
end

The @return is important or the warning comes back

Option 2

If you really wanted this functionality you could use @overload which would look like

class A
  # @!macro [attach] add_setting
  #   @!method $1
  #     @return [Object] the $1 of the a
  #   @!method $1=(value)
  def self.add_setting(setting)
  end
  # @overload color=(value)
  #   @param value [String] Hexadecimal representation of color
  # @macro add_setting
  add_setting :color
  add_setting :name
end

This will cause the getter method for name and color to be documented as:

• name => Object
  
  
  • Returns the name of the a
• color => Object
  
  
  • Returns the color of the a

but the setter methods will look like

• name=(value) => Object
• color=(value) => Object
  
  
  • Parameters:
  • value(String) -- Hexadecimal representation of color

because we overloaded color=.

That being said this doesn't really help you as it would probably consist of individually documenting the methods anyway.

Other options:

• Ignore the warnings
• quite all warnings completely -q
• Checkout this Thread

---

Related Topics