A disclaimer or two for Optional

[Joe Bowbeer]

Value-unsafe is a poor term but at least it makes it clear that this is a
new thing, for Java. (And I can google for value-unsafe operations.)

Warning that legal constructs today might fail in arbitrary ways in the
future is not a message that Java programmers have ever received, and I
would avoid crossing that line here. It is better to describe what uses
will allow more performant implementations in the future. In that respect,
the best sentence would explain the optimal ways to use Optional.  I think
it's ok to use the term value type.

On Friday, November 22, 2013, Brian Goetz wrote:

> OK, trying to wrap this loose end up...
>
> Doug's suggestion was:
>
>       /**
>>       * Returns an {@code Optional} with the specified present non-null
>> value.
>> adding...
>> * The returned instance need not be unique. Thus the results of
>> * comparing two instances using @code{==}, or using one as the
>> * argument for a @code{synchronized} block are arbitrary and should
>> * be avoided.
>>       *
>>       * @param <T> the class of the value
>>       * @param value the value to be present, which must be non-null
>>       * @return an {@code Optional} with the value present
>>       * @throws NullPointerException if value is null
>>       */
>>      public static <T> Optional<T> of(T value) {
>>          return new Optional<>(value);
>>      }
>>
>>
> Joe suggested "more carrot, less stick", promising benefits for following
> the rules rather than threatened punishment for not doing so.  Though not
> sure what carrot to offer without explaning the whole story.
>
> Perhaps generalizing:
>
> ... the use of value-unsafe operations, including comparing ... should be
> avoided.
>
> (which begs the question, what is "value-unsafe" :(
>