RFR: 8177418: NPE is not apparent for methods in java.util.TimeZone API docs [v6]

[Naoto Sato]

On Wed, 25 Jan 2023 00:31:26 GMT, Justin Lu <jlu at openjdk.org> wrote:

>> When their input is null, the following methods in java.util.TimeZone throw a NullPointerException:
>> 
>> TimeZone.getTimeZone(String ID)
>> TimeZone.setID(String ID)
>> TimeZone.inDaylightTime(Date date)
>> 
>> For example, 
>> 
>> 
>> String someID = null;
>> TimeZone tz1 = TimeZone.getTimeZone(someID);
>> ``` 
>> 
>> throws a `NullPointerException`
>> 
>> However this is not documented in the API docs in the form of a _throws:_ section.
>> 
>> This change updates the documentation to make this apparent.
>> 
>> Aditionally, updates the javadoc of SimpleTimeZone.inDaylightTime(Date date) to inherit the _ at throws:_
>
> Justin Lu has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Minor punctuation

src/java.base/share/classes/java/util/TimeZone.java line 297:

> 295:      * the time zone object.
> 296:      * @param ID the new time zone ID.
> 297:      * @implSpec The default implementation throws a

Usually @implSpec follows the method description, apart from other tags. See https://openjdk.org/jeps/8068562

src/java.base/share/classes/java/util/TimeZone.java line 402:

> 400:      * @param style either {@link #LONG} or {@link #SHORT}
> 401:      * @param locale   the locale in which to supply the display name.
> 402:      * @implSpec The default implementation throws a

Same as above.

src/java.base/share/classes/java/util/TimeZone.java line 404:

> 402:      * @implSpec The default implementation throws a
> 403:      * {@code NullPointerException} if {@code ID} is {@code null}.
> 404:      * Additionally, an {@code IllegalArgumentException} will be thrown if

I'd concatenate these with "or". Also, I think `IllegalArgumentException` has higher priority in the case of both being null/invalid.

src/java.base/share/classes/java/util/TimeZone.java line 407:

> 405:      * {@code style} is invalid.
> 406:      * @return the human-readable name of this time zone in the given locale.
> 407:      * @throws IllegalArgumentException This method may throw a

a -> an

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

PR: https://git.openjdk.org/jdk/pull/11888