mojombo / tomdoc

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

Generic Sections #35

Closed trans closed 12 years ago

trans commented 12 years ago

Tomdoc might support generic section via custom tags. Any word followed by a colon at the start of line, not otherwise recognized could be a generic tagged section, e.g.

  # Public: The typical foo method.
  #
  # Note: Foo methods are for examples.
  #
  # Returns nothing.
  def foo
     ...
  end

So in this case a "Note" section would parsed out. In this way documenters can create their own sections as needed.

mojombo commented 12 years ago

Any paragraphs at the top of the documentation are considered part of the description, so the example you pasted is valid TomDoc. I think this flexibility is enough to handle most cases without having to include special syntax handling rules.

trans commented 11 years ago

There is a lot more that can be done with such a convention. I think my Note example maybe made it too easy for this to be dismissed as part of the description. Take this example instead:

  # Public: The typical foo method.
  #
  # Note: Foo methods are for examples.
  #
  # n - number of things
  #
  # Returns nothing.
  #
  # Author: Bill Baxley
  # Since: 2.0.0
  def foo(n)
     ...
  end

This would be a way to add meta-information about who wrote a method, and since what version it has been available. Do you think additional information of that nature should still be in the description?

  # Public: The typical foo method.
  #
  # Note: Foo methods are for examples.
  #
  # Author: Bill Baxley
  # Since: 2.0.0
  #
  # n - number of things
  #
  # Returns nothing.
  def foo(n)
     ...
  end

I guess my problem with this is that the arguments, which are generally of more interest, get pushed further and further down. It starts to look pretty ugly.

trans commented 11 years ago

Hmm... thinking about it some more. I think these tags could be okay relegated to the description area if it were possible to more clearly designate the arguments section.

  # Public: The typical foo method.
  #
  # Note: Foo methods are for examples.
  #
  # Author: Bill Baxley
  # Since: 2.0.0
  #
  # Arguments
  #
  # n - number of things
  #
  # Returns nothing.
  def foo(n)
     ...
  end