mojombo / tomdoc

A flexible code documentation specification with human readers in mind.
333 stars 47 forks source link

Downplay Examples #51

Open trans opened 10 years ago

trans commented 10 years ago

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:

# 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'
#
# 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

Instead of

# Public: Duplicate some text an arbitrary number of times.
# If no count is given then count defaults to 2.
#
# text  - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Examples
#
#    multiplex('Tom', 4)
#    # => 'TomTomTomTom'
#
#    multiplex('Tom')
#    # => 'TomTom'
#
# Returns the duplicated String.
def multiplex(text, count)
  text * count
end

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.

trans commented 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
trans commented 10 years ago

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