[Doc-SIG] epydoc 1.1 release

[Edward Loper]

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