Name: eaT66865 Date: 09/16/2002


Doc.position() says it returns null "if no position is
available". The conditions under which that may be true
need to be documented.

Neal wrote: A default constructor will return null, because
    it has no location in the source file.

The comment also says it returns "the source position of the
documented entity".

To me, that read as "first line of the comment", which is
hopelessly wrong. A sentence which is less open to misinterpretation
would be helpful. Maybe: "The position in the source file of
the first line of the declaration for the program element that the
comment documents." (Accurate, but verbose. Shorter would be better.)

======================================================================