Search code examples
rubyrdoc

How to automatically document Metaprogrammed attr_accessors using RDoc?

FIRST, I would like to customize RDoc such that it automatically recognizes each key of the attrs hash foo and bar of the following code:

class SomeClass
  def initialize( args = { }) 
    attrs = { 'foo'  => nil,
              'bar'    => 'us'}
    attrs.each_key{ |key| (class << self; self; end).send( :attr_accessor, key.to_sym)}

    attrs.each_key do |key|
      attrs[ key] = args[ key] if( args.has_key?( key))
      raise "No #{key} defined" if( attrs[key] === nil))
    end

    attrs.each {|key, value| instance_variable_set( "@#{key}", value)}
  end
end

As if I had initialized them as follows:

class SomeClass
  attr_accessor :foo, :bar
  def initialize( foo = nil, bar = 'us') 
      raise "No foo defined" if( foo === nil))
      @foo = foo
      @bar = bar
  end
end

I am able to do the following and have the accessors show up properly as Attributes:

class SomeClass
  ##
  # :attr_accessor: foo

  ##
  # :attr_accessor: bar

  ##
  # this is a comment for a the initialize method

  def initialize( args = { }) 
    attrs = { 'foo'  => nil,
              'bar'    => 'us'}
    attrs.each_key{ |key| (class << self; self; end).send( :attr_accessor, key.to_sym)}

    attrs.each_key do |key|
      attrs[ key] = args[ key] if( args.has_key?( key))
      raise "No #{key} defined" if( attrs[key] === nil))
    end

    attrs.each {|key, value| instance_variable_set( "@#{key}", value)}
  end
end

But I would like to be able to have RDoc recognize these automatically!

SECOND, I would like to be able to make comment relevant to their definitions in a manor similar to the following and have the comments show up in the documentation: 

class SomeClass
  def initialize( args = { }) 
    attrs = { 
              ##
              #This stores your Foo
              'foo'  => nil,
              ##
              #This stores your Bar
              'bar'    => 'us'}
    attrs.each_key{ |key| (class << self; self; end).send( :attr_accessor, key.to_sym)}

    attrs.each_key do |key|
      attrs[ key] = args[ key] if( args.has_key?( key))
      raise "No #{key} defined" if( attrs[key] === nil))
    end

    attrs.each {|key, value| instance_variable_set( "@#{key}", value)}
  end
end

LAST, I would like their default values automatically listed as well (i.e. within the documentation it would list with the attributes that by default foo = nil and bar = 'us').

I have been examining the RDoc documentation for the Ruby code parser RDoc::Parser::Ruby and I would like to build a plugin as described in the RDoc Developer Introduction but I am unsure of how to even begin.

1) Is there something out there which already accomplishes what I have described? 2) If nothing exists, could someone please point me to an example plugin accomplishing similar functionality?

Solution

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

    Also see my other related questions: