Generic Sections

[trans]

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]

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]

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]

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