Open trans opened 10 years ago
Btw, it was for this reason that I suggested Arguments
be an optional section header, b/c when you have examples in the description it helps readability. e.g.
# Public: Duplicate some text an arbitrary number of times.
#
# multiplex('Tom', 4)
# # => 'TomTomTomTom'
#
# If no count is given then count defaults to 2.
#
# multiplex('Tom')
# # => 'TomTom'
#
# Arguments
#
# text - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Returns the duplicated String.
def multiplex(text, count)
text * count
end
Hmm... now that I have written this out, it gives me an alternative idea. What if there were a detailed explanation section? Not sure what it would be called exactly, maybe Explanation
or Details
, but in any case, it makes sense that the first description would simply be a summary description and a subsequent section could go into detail. e.g.
# Public: Duplicate some text an arbitrary number of times.
#
# text - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Explanation
#
# Given a string and a count, multiplex will copy the string as many times
# as the count directs and join the copies together into a new string.
#
# multiplex('Tom', 4)
# # => 'TomTomTomTom'
#
# If no count is given then count defaults to 2.
#
# multiplex('Tom')
# # => 'TomTom'
#
# Returns the duplicated String.
def multiplex(text, count)
text * count
end
I think the Examples section should be downplayed a bit. What I mean by that is, I have found the my documentation is usually more readable when examples are given as part of the description, rather then explaining everything and then giving a bunch examples at the end. For example:
Instead of
For this example it's not so bad, I might even be inclined to document it the second way b/c there it is only one option. But methods with a two or more options, and even worse, those that have options of options, it's much more pronounced.