JDK 9 RFR(s): 8167981: Optional: add notes explaining intended use

[Paul Sandoz]

> On 18 Apr 2017, at 20:29, Martin Buchholz <martinrb at google.com> wrote:
> 
> +     * The methods {@link #orElse(java.lang.Object) orElse()} and
> 
> It's sad that in 2017 we still can't write
> {@link #orElse(T)}
> ... but ... we can and should write
> {@link #orElse(Object) orElse(T)}
> making the source and html more readable (orElse is not nullary)
> 
> + * {@code OptionalDouble} is primarily intended for use as a method return
> type where
> + * there is a clear need to represent "no result," and where using {@code
> null}
> + * is likely to cause errors. A variable whose type is {@code
> OptionalDouble} should
> 
> The obvious alternative to returning OptionalDouble is returning double,
> where null is not possible. I would elide """and where using {@code null}
> + * is likely to cause errors""" unless you want to explicitly compare with
> the alternative of returning Double,not double.
> 

“… and where using the default value (@code {0.0d}) is likely to cause errors."

?

Paul.

> (More generally, it seems like Optional would have more value if there was
> compiler enforcement of its never-null-ness.)
> 
> 
> On Tue, Apr 18, 2017 at 6:23 PM, Stuart Marks <stuart.marks at oracle.com>
> wrote:
> 
>> Hi all,
>> 
>> Please review this small set of non-normative documentation changes for
>> java.util.Optional and related classes.
>> 
>> The notes describe the primary intent of Optional to be used as a return
>> value, and recommend avoiding using null as the value of a variable of
>> Optional type. Also, a note is added to get() directing readers to look at
>> orElse() and orElseGet().
>> 
>> Corresponding changes are also made to the primitive specializations
>> OptionalDouble, OptionalInt, and OptionalLong.
>> 
>> Bug:
>>        https://bugs.openjdk.java.net/browse/JDK-8167981
>> 
>> Webrev:
>>        http://cr.openjdk.java.net/~smarks/reviews/8167981/webrev.0/
>> 
>> Thanks,
>> 
>> s'marks
>>