RFR: 8251496: Fix doclint warnings in jdk.net.httpserver

[Daniel Fuchs]

On Tue, 8 Sep 2020 16:22:15 GMT, Patrick Concannon <pconcannon at openjdk.org> wrote:

> Hi,
> 
> Could someone please review my doc-only fix for JDK-8251496 - ‘Fix doclint warnings in jdk.net.httpserver’ ?
> 
> This fix addresses the warnings generated by `javadoc -Xdoclint` due to missing/incomplete API documentation for
> several classes within `jdk.net.httpserver`.
> CSR: https://bugs.openjdk.java.net/browse/JDK-8252585
> 
> Kind regards,
> Patrick

Thanks for taking this on Patrick. This mostly looks good to me, with the comments below. Thanks for adding the new
tests to cover the added assertion. That's a nice touch ��

best regards,

-- daniel

src/jdk.httpserver/share/classes/com/sun/net/httpserver/Authenticator.java line 93:

> 91:
> 92:         /**
> 93:          * Creates a {@code Success} instance with given Principal.

For consistency with line 103 below maybe Principal should be quoted `{@code Principal}` here and at line 95 too

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java line 69:

> 67:
> 68:     /**
> 69:      * Creates a HttpExchange.

I'd suggest to keep consistent... You have been using `* Constructor for subclasses to call` at other places. Maybe you
should use that sentence here too.

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpContext.java line 45:

> 43:
> 44:     /**
> 45:      * Creates a HttpContext.

I'd suggest to keep consistent... You have been using * Constructor for subclasses to call at other places. Maybe you
should use that sentence here too.

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

> 43:
> 44:     /**
> 45:      * Creates a Filter.

I'd suggest to keep consistent... You have been using * Constructor for subclasses to call at other places. Maybe you
should use that sentence here too.

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsParameters.java line 30:

> 28: import java.net.InetSocketAddress;
> 29:
> 30: //BEGIN_TIGER_EXCLUDE

I don't have the context here - but if we're removing this import then I guess we should be removing the `// BEGIN` and
`// END` comments too?

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsParameters.java line 61:

> 59:
> 60:     /**
> 61:      * Creates a HttpsParameters.

Same comment about consistency.

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsParameters.java line 68:

> 66:      * Returns the HttpsConfigurator for this HttpsParameters.
> 67:      *
> 68:      * @returns HttpsConfigurator for this instance of HttpsParameters.

Probably would be worth saying if the result can be `null`. I guess it can. However I realize that this may be a more
general issue with the whole API, so maybe what you have is OK for now, and we should leave further tightening of the
spec to a followup.

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

Changes requested by dfuchs (Reviewer).

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