ruby - How to document a constant created in a DSL with YARD?

Question

I have a DSL method which adds a constant (it's legacy code so don't hate). This isn't the exact code, but it's descriptive enough.

class Foo
  bar :awesome, "cold Coke"
  bar :lame,    "warm Coke"

  def bar(name, value)
    const_set(name, value)
  end
end

I am attempting to document the constants AWESOME and LAME using Yard. I would expected there to be a @!constant tag, but there is not.

Can anyone help with this?

Answer 1

I think this should get Yard to do the right thing:

# @!parse AWESOME = "cold Coke"
# @!parse LAME = "warm Coke"

This could be expanded upon using Yard's macro attachments, if you have bar everywhere in your code. However, the macro behaviour does not seem to like constants, or allow for string processing that your DSL might do with contents (e.g. converting to upper case). I could get basic behaviour, that might be adaptable for your needs, as follows:

 # @!visibility private
 # @!macro [attach] bar
 #   @!method $1()
 #   @return [String] always "$2"
 def self.bar(name, value)
   const_set(name, value)
 end

bar :awesome, "cold Coke"
bar :lame,    "warm Coke"

Which ends up looking a little like this:

---

Instance Method Summary

• (String) awesome

  • Always "cold Coke".

    ---

• (String) lame

  • Always "warm Coke".

    ---