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

[Stuart Marks]

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