[Doc-SIG] Syntax for fields
Edward D. Loper
edloper@gradient.cis.upenn.edu
Sat, 14 Apr 2001 14:46:24 EDT
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