[Doc-SIG] Syntax for fields

[Edward D. Loper]

I've been actually using my markup language to document some things,
and my current syntax for fields seems somewhat problematic.  I've
been using expressions like::

  author: Edward Loper
  param n: The size of the list to return.
  type n: C{int}
  return: A list containing all of the prime numbers between
          2 and C{x}, inclusive.

(The syntax is essentially the same as it is for list items, except
that "\w+ \w+:" is the bullet instead of "-" or "(\d+\.)+")

The problem is that there's too much overlap between the form of such
expressions and the form of natural language expressions like::

  Consider this: blah blah..
  A problem: .sdf dfs...
  However: ...

And I don't feel comfortable forbidding people to use expressions like
that (among other things, it's just not something people will
remember not to do).

I was using the "param n:" style mainly because it's easy to read.
One other option is to mimic javadoc, and do something like::

  @author Edward Loper
  @param n The size of the list to return

or::

  @author: Edward Loper
  @param n: The size of the list to return

or::

  @author Edward Loper
  @param(n) The size of the list to return

Another option might be to only allow captizlied field names::

  AUTHOR: Edward Loper
  PARAM n: The size of the list to return

Although this looks somewhat ugly to me.  Yet another option would be
to only count "<tag>:" or "<tag> <arg>:" as a field if <tag> is one of
a small finite set of reserved words..  But that means we can never
expand the tag set in a backwards-compatible way, and that we can't
have alternative tag-sets for code written in different languages.

Other ideas?  Which (if any) of these alternatives are appealing?

-Edward