[Doc-SIG] epydoc 1.1 release
Edward Loper
edloper@gradient.cis.upenn.edu
Fri, 1 Nov 2002 12:30:55 -0500 (EST)
On Fri, 1 Nov 2002, M.-A. Lemburg wrote:
> > Actually, the only real similarity between epytext and javadoc comments
> > is that the @field's look roughly similar.
>
> That's what I was looking at. Your @field defs look very similar,
> but aren't compatible, e.g. was there a reason to add colons ? (this
> is really what I'm interested in; not the HTML formatting used
> in JavaScript)
For those who are not familiar with javadoc, their field syntax is:
@param x description...
@author description...
Whereas my field syntax is
@param x: description...
@author: description...
The problem I have with javadoc's syntax is that the markup language
itself has to specify which fields take arguments and which don't. That
goes against epytext's philosophy, where everything should be as simple
and consistant as possible. By adding a colon, epytext doesn't need to
know anything about what the set of fields are; and the later systems that
actually use the fields can complain if they're invalid in some way.
Another reason for using the colon is that strings of the form "@...:" are
much less likely to occur "naturally" than strings of the form "@...".
(Another difference is that using a colon would let you provide optional
arguments, but none of the fields I have defined use optional arguments,
and I doubt that any will.)
> Thanks for the instructions. I think I'll have a go once we're
> sure that we need this.
Ok, thanks.
-Edward