Using Rdoc when auto-creating methods

[Bret Pettichord]

For the Watir library, we had a lot of repetitive wrapper methods with
a lot of duplicated logic. So i refactored the code. I've attached a
portion of the code below.

This works fine, except for one thing. I can't generate rdoc for the
methods that are now created using these "macro" class methods. I've
looked at the doc for rdoc and the -A flag, but nothing really seemed
to work.

At this point, i am thinking that the best solution would be convert
the comments into here documents, pass them as an additional argument
to the class methods and then extend the methods to write out
"prototype" methods, with comments, to a separate *.rb file that rdoc
could read (and then delete).

Has any one else ever run into a situation like this? Any other ideas?

Bret

private
def self.def_creator(method_name, klass_name=nil)
klass_name ||= method_name.to_s.capitalize
class_eval "def #{method_name}(how, what)
#{klass_name}.new(self, how, what)
end"
end

def self.def_creator_with_default(method_name, default_symbol)
klass_name = method_name.to_s.capitalize
class_eval "def #{method_name}(how, what=nil)
how, what = process_default
:#{default_symbol}, how, what
#{klass_name}.new(self, how, what)
end"
end

# this method is the main way of accessing a frame
# * how - how the frame is accessed. This can also just be
the name of the frame
# * what - what we want to access.
#
# Typical usage:
#
# ie.frameindex, 1)
# ie.framename, 'main_frame')
# ie.frame('main_frame') # in this case, just a name
is supplied
public
def_creator_with_default :frame, :name

# this method is used to access a form.
# available ways of accessing it are, :index, :name, :id,
:method, :action, :xpath
# * how - symbol - WHat mecahnism we use to find the
form, one of the above. NOTE if what is not supplied this parameter is
the NAME of the form
# * what - String - the text associated with the symbol
def_creator_with_default :form, :name

# This method is used to get a table from the page.
# :index (1 based counting) and :id are supported.
# NOTE :name is not supported, as the table tag does not have
a name attribute. It is not part of the DOM.
# :index can be used when there are multiple tables on a page.
# :xpath can be used to select table using XPath query.
# The first form can be accessed with :index 1, the second
:index 2, etc.
# * how - symbol - the way we look for the table. Supported
values are
# - :id
# - :index
# - :xpath
# * what - string the thing we are looking for, ex. id,
index or xpath query, of the object we are looking for
def_creator :table

 

[ara.t.howard]

For the Watir library, we had a lot of repetitive wrapper methods with
a lot of duplicated logic. So i refactored the code. I've attached a
portion of the code below.

This works fine, except for one thing. I can't generate rdoc for the
methods that are now created using these "macro" class methods. I've
looked at the doc for rdoc and the -A flag, but nothing really seemed
to work.

At this point, i am thinking that the best solution would be convert
the comments into here documents, pass them as an additional argument
to the class methods and then extend the methods to write out
"prototype" methods, with comments, to a separate *.rb file that rdoc
could read (and then delete).

Has any one else ever run into a situation like this? Any other ideas?

that's a good approach. another is


#
# docs describing this __family__ of methods
#
LIST_OF_ATTRIBUTES = %w[
one
two
three
]

LIST_OF_ATTRIBUTES.each{|m| gen_method m}

which may be sufficient for you purposes.

-a