A disclaimer or two for Optional

[Brian Goetz]

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