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

[Stuart Marks]

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