hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Roland Weber <http-as...@dubioso.net>
Subject Re: svn commit: r391135 - in /jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http: ./ impl/
Date Tue, 04 Apr 2006 16:02:09 GMT
Hi Odi,

first let me thank you for the work you put into documenting
the interfaces. Good job! Now for the details...

The format for inline JavaDoc links is {@link <target> <text>}.
The <text> is optional (I've had problems with earlier versions
of JavaDoc auto-inserting argument lists with full package names),
but the curly braces are required for the JavaDoc tool to detect
the inline link.

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@link}

>  /**
>   * <p>An HTTP header.</p>

I know this wasn't inserted by you, I just happened to see it
in the commit mail. The <p>...</p> tags here are pointless.
They don't seem to cause any harm (here), but the algorithm
that picks the first sentence for the summary pages is supposed
to stop after the first point followed by a whitespace, and
</p> is not a white space. We should remove such tags if we
happen to come across them.

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#descriptions


Note to self: the "writingdoccomments" site recommends writing
"Gets the label." rather than "Get the label." I'm sure I've read
the opposite recommendation somewhere sometime, and have tried to
stick to that for http-async. I'll change back to the (actually)
recommended style, which is what I'm used to anyway :-)

cheers,
  Roland

---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org


Mime
View raw message