tomdoc
tomdoc copied to clipboard
mojombo
Add signature section.
Slight typo at The signature section allows you specify assuming you're missing a to in there. This looks great
Actually, I don't like how this moves Returns out from the end. More than anything else I kind of feel like Returns is the anchor of all of TomDoc- I always know it's going to be on the block's end, period. I'd push Signature above Returns.
The goal was to keep the signature at the bottom to mimic where a real method signature would be when documenting real methods. But I do agree that the Returns section coming last is a nice anchor of sorts. Even as-is the Signature section doesn't allow for easy scanning of method names like real code does. I shall think on this.
How are class (singleton) methods supposed to be documented in the Signature section?
In RDoc all methods marked up in the Signature section are assumed to be instance methods.
Any updates to this? I agree that the Returns should be at the end, rather than pushed up by Signature
What do you guys think about this change? It adds a separator line to help distinguish the signature docs from the method docs.
I'm for it! I had the same concerns about the signature section, and this seems like an elegant solution.
I'm not so sure about it. Writing TomDoc feels extremely natural and I think the separator is a step in the opposite direction. I also think the Returns section should always be the last documentation segment. To me, this looks like it would be nicer on the eyes:
# Public: Find Records by a specific field name and value. This method
# will be available for each field defined on the record.
#
# args - The value or Array of values of the field(s) to find by.
#
# Examples
#
# find_by_name_and_email("Tom", "[email protected]")
#
# Signature
#
# find_by_<field>[_and_<field>...](args)
#
# field - A field name.
#
# Returns an Array of matching Records.
@mojombo, What about this PR? I like it all, but not the separator, I'm totally agreed with @injekt in this. But the idea its the best way to document metaprogramming that I ever found.
