RFR: 8251496: Fix doclint warnings in jdk.net.httpserver [v3]

[Patrick Concannon]

On Tue, 8 Sep 2020 16:34:12 GMT, Daniel Fuchs <dfuchs at openjdk.org> wrote:

>> Patrick Concannon has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   8251496: reworded abstract cstr comments; removed unnecessary punctuation
>
> 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

Changed to use {@code Principal}.

> 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.

Replaced wording -- now using `* Constructor for subclasses to call`.

> 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.

Replaced wording as suggested.

> 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.

Replaced wording as suggested.

> 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?

Thanks for spotting this. IntelliJ re-arranged the imports automatically. I reverted it back to its original state

> src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpsParameters.java line 61:
> 
>> 59:
>> 60:     /**
>> 61:      * Creates a HttpsParameters.
> 
> Same comment about consistency.

Replaced wording as suggested.

> 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.

I have opened another issue for this -- https://bugs.openjdk.java.net/browse/JDK-8252822 -- and will address them there

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

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