Signatures / Dynamic Methods

[trans]

To me a signature is something to describe alternate arguments, not dynamic method definitions. For example:

# Public: Find all of something.
#
# Signatures
#
#   find_all(name)
#   find_all(name=>pattern)
#
# name    - The name.
# pattern - Alternate pattern.
#
# Returns something.
def find_all(*args)
   ...
end

This is a fair bit different then what TomDocs signatures do. And I do not see how the two can be quite reconciled. Primarily b/c dynamic signatures, like what TomDoc is describing, do not necessary need to come before an actual method definition. That make them harder to parse. How does the document parser recognize them?

So giving it some thought it occurs to me that it could be documented as a meta comment, so that a pseudo-method can be defined in a more usual manner. It could be something like this (using the example from the spec):

# Dynamic Methods
#
# # Public: Find Records by a specific field name and value. This method
# # will be available for each field defined on the record.
# #
# # field - A field name.
# # args - The value or Array of values of the field(s) to find by.
# #
# # Examples
# #
# #   find_by_name_and_email("Tom", "[email protected]")
# #
# # Returns an Array of matching Records.
# def find_by_<field>[_and_<field>...](args)
# end

The Dynamic Methods header would tell the parser what to expect. The rest just looks like regular Ruby code except double commented, and, of course, the method "signature" can have [] and <> markup.