A disclaimer or two for Optional

[Brian Goetz]

> By "there may be hope", you mean there may be hope of reducing misuse --
> as-if-full-reference-type use -- of these new-in-8 valueish types while
> they are not yet full value types by adding class-specific disclaimers?

Exactly.

> If so, Optional is probably the least appropriate candidate for such
> special pleading. Since avoidance of null is a big motivation for
> Optional in the first place, you're far less likely to find folks doing
> comparison to null (or other Rose no-nos) with Optional than with any
> other valueish-type you can think of. Users of Optional have already got
> the religion; no need to preach to the choir.

They are more likely to behave, but the special pleading has two 
motivations, only one of which is addressed above:
  - discourage users from doing wrong things
  - provide cover so that when we break code that does wrong things, 
they were adequately warned

> I think a better way to prepare folks for such a language change would
> be to create a separate section in an overview or package doc that
> describes valueish types and what you shouldn't do with them, perhaps
> mentioning the possibility of a language change that would make such
> misuse entirely broken, and add links from the class comment for all
> such types to this section.

In a perfect world, the visitor from Flatland would show up and lay the 
entire future out for us.  We're a few days from Public Review; we're in 
"better than nothing" territory here.