Closed trans closed 13 years ago
I agree that the attr_ stuff may need some more consideration.
For example, describing the "Returns" statement for attr_writer
is futile as there's no way to control the return value -- it will always be the value being assigned.
I had a thought about this. What if you could just do this:
# Returns the String name of the user.
attr_reader :name
# Sets the String name of the user.
attr_writer :name
Essentially allowing each section to be optional so that needs like this can be met in a concise way. I could even be convinced that attr_accessor is ok. Something like:
# Returns/Sets the String name of the user.
attr_accessor :name
Which could be understood by parsers and split into the two methods for printout.
I would definitely prefer to write
# Returns the String name of the user.
attr_reader :name
than the documented method.
I also think enabling attr_accessor is prudent.
Would you make these part of the specification, please?
A shorter syntax is now allowed in 1.0.0.pre. See next
branch.
You attr_writer docs are a bit annoying. 5 lines per writer? Really? Side note: I have always wanted to be able to document attributes via comments on their right side --though maybe that's asking too much.