RFR: 8253470: Javadoc clean up in Filter and Headers

[Daniel Fuchs]

On Wed, 30 Sep 2020 10:02:06 GMT, Patrick Concannon <pconcannon at openjdk.org> wrote:

> Hi,
> 
> Could someone please review my doc-only fix for JDK-8253470 - 'Javadoc clean up in Filter and Headers' ?
> 
> This fix is set of formatting changes intended to clean up the javadoc of the following classes :
> 
> `com.sun.net.httpserver.Filter`
> `com.sun.net.httpserver.Filter.Chain`
> `com.sun.net.httpserver.Headers`
> 
> This issue is a sub-task of [JDK-8252822](https://bugs.openjdk.java.net/browse/JDK-8252822)
> 
> Kind regards,
> Patrick

Thanks for working on this issue Patrick!

A few comments below:

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java line 40:

> 38:  * are organised in chains, and are associated with {@link HttpContext} instances.
> 39:  *
> 40:  * <p> Each Filter in the chain, invokes the next filter within its own

Here `Each Filter` should be either `Each filter` or `Each {@code Filter}`

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java line 41:

> 39:  *
> 40:  * <p> Each Filter in the chain, invokes the next filter within its own
> 41:  * {@link #doFilter(HttpExchange, Chain)} implementation. The final Filter in

Same here for `the final Filter` - should be either `the final filter` or `the final {@code Filter}`

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Filter.java line 109:

> 107:      *     <li> Filter the request body or the response body, by creating suitable
> 108:      *     filter streams and calling {@link HttpExchange#setStreams(InputStream, OutputStream)}.
> 109:      *     <li> Set attribute Objects in the exchange, which other filters or

`Set attribute objects` ...

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Headers.java line 62:

> 60:  *     <li>{@link #add(String,String)} adds the given header value to the list for the given key
> 61:  *     <li>{@link #set(String,String)} sets the given header field to the single value given
> 62:  *     overwriting any existing values in the value list

For consistency, either:
  - no item should end with a punctuation sign
  - or all of them should end with a coma, except the last that should end with a full stop.
  - or all of them should end with a full stop.

I am not sure what is the best, but it is weird that the first item ends with a full stop and the other two don't.

-------------

Changes requested by dfuchs (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/429