RFR: 8028816: Add value-type notice to Optional* classes

[roger riggs]

Hi Mike,

It is cleaner specification avoid mixing normative language and 
informative language in the same sentence.

"..may have unpredictable effects and should be avoided"


The first part is specifying the unpredictable behavior and the 2nd part 
is advice to a user of the API.

"may" is weak language, it is cleaner/clearer to say it is unpredictable 
without qualification.

I believe it is preferred to use "{@docRoot}" instead of ".." for the 
link reference in java.util.Optional

$.02, Roger

p.s. I did not find the discussion mentioned at the link to the lambda 
archive.

On 12/3/2013 5:21 PM, Mike Duigou wrote:
> Hello all;
>
> There's been a discussion on the lambda spec experts list (http://mail.openjdk.java.net/pipermail/lambda-spec-experts/) about adding a notice to the Optional classes about implications of their likely future as values. This discussion recently completed so now there's a doc patch to review:
>
> http://cr.openjdk.java.net/~mduigou/JDK-8028816/0/webrev/
>
> I have already reviewed this but will hold off pushing it for a few hours in case someone notices a mistake that I did not.
>
> Mike