Martin 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)
Well we're not going to fix the tooling right now, but I take your point about
the trailing empty parens. I often use foo() as a typographic marker to indicate
that "foo" is a method, even if it's not nullary; the javadocs aren't terribly
consistent about this. However, in this case I agree that they're unnecessary
since the wording clearly indicates that it's a method, and it's also a link
directly to the method declaration. So, I've removed the parens.
+ * {@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.
I did have in mind the possibility of the return of a nullable Double
(respectively, Integer and Long). I did a quick grepcode search and I was pretty
easily able to find occurrences of methods that returned nullable Integer
references. I couldn't tell whether these were intended to indicate "no result"
or whether it was just sloppy programming.
But Paul also points out that 0.0d (resp., 0 and 0L) might be used as default
values. For int and long I can also imagine -1, MIN_VALUE, etc. also being used
as sentinels for "no result."
In any case I think it's best to sidestep this entire discussion for the
purposes of this text and simply omit the mention of null as Martin suggests.
This results in
OptionalDouble is primarily intended for use as a method return type where
there is a clear need to represent "no result."
Full stop. (Respectively for OptionalInt and OptionalLong.) I think that's clear
enough.
Revised webrev:
http://cr.openjdk.java.net/~smarks/reviews/8167981/webrev.1/
s'marks
On 4/19/17 9:58 AM, Paul Sandoz wrote:
On 18 Apr 2017, at 20:29, Martin Buchholz <marti...@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.ma...@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
