Re: YA Socket timeout patch

[Nic Ferrier <nferrier at tf1 dot tapsellferrier dot co dot uk>]

Nic Ferrier wrote:
>> I use the first line (the one with the double **) to be a very brief
>> intro, as per the Sun suggestions.

Per replied:
>This is *not* what Sun suggests.  The /** line is otherwise  *empty*
>according to Sun's documnetation.  See: 
>http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
>especially the section "General Form of a Doc Comment".  We
>are not obliged to follow Sun's recommendations, of course.

Yes. To clarify: the first line of a doc comment should be a short
desription, quoting from the doc standard (which is the doclet
reference):


 The first sentence of each doc comment should be a summary sentence,
 containing a concise but complete description of the declared entity.
 This sentence ends at the first period that is followed by a blank,
 tab, or line terminator, or at the first tag.  Javadoc copies this
 first sentence to the member summary at the top of the HTML page.

This, AFAIK is the same for the info doclet being developed under the
Classpath tools project.


In the statement from my mail I did not mean that Sun's standard
stated that the doc comment should go on the line with the double **,
meerly that it is useful to put the summary statement there, it saves
lines and provides the useful search trick.


It seems to me it would be useful to define some cross GNU standards
for javadoc comments... but then again perhaps that ought to wait
until the info doclet is done.


Nic