[Doc-SIG] field syntax (was re: lists & blank lines)

[Goodger, David]

We've monopolized Doc-SIG all day, might as well continue...

[Edward Loper, referring to fields]
> > > ... and at the end of the docstring)
> > 
> > Again, why? Why restrict fields to the end of a docstring? Seems
> > artificial to me.
> 
> It is somewhat artificial.  The reasoning was as follows: the 
> position of the fields does not convey any semantic information;
> tools are likely to disregard the position when formatting
> their output.  If we let people put them wherever they want in
> the docstring, then they may assume that they will appear in
> that position in the output of doc formatting tools (i.e., that
> their position *does* convey semantic information).  This is
> dangerous, and should be stamped out. :)  So, put all fields
> at the end, so no one will get confused.

I don't see why your first assumption should hold true. It is the foundation
of the rest of your argument.

I think you need to define your concept of "fields" better for us here on
the SIG (note: assume no previous knowledge of JavaDoc). Give a detailed
example. Why isn't position significant? What about field order? Sounds like
you're describing a dictionary-like structure associated with each
docstring. Can a field be used more than once, or must each field be unique
per docstring?

/DG