Re: svn commit: r391135 - in /jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http: ./ impl/

[Roland Weber <ht...@dubioso.net>]

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

Re: svn commit: r391135 - in /jakarta/httpcomponents/trunk/http-core/src/java/org/apache/http: ./ impl/

[Ortwin Glück <od...@odi.ch>]

Roland Weber wrote:
> 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}

Thanks for pointing it out. I use braces normally but this time somehow 
didn't and Eclipse didn't complain. Sorry for breaking the tool - I 
didn't actually run it. Which - once again - shows that all code is 
broken as long as it is untested.

>>  /**
>>   * <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 :-)

I like the third person form too.

> cheers,
>   Roland

-- 
[web]  http://www.odi.ch/
[blog] http://www.odi.ch/weblog/
[pgp]  key 0x81CF3416
        finger print F2B1 B21F F056 D53E 5D79 A5AF 02BE 70F5 81CF 3416

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