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

[Martin Buchholz]

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

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