[Doc-SIG] field syntax (was re: lists & blank lines)
Goodger, David
dgoodger@atsautomation.com
Mon, 16 Apr 2001 18:32:02 -0400
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