Add some notes to the API specification of java.util.Optional to describe Optional's intended use more clearly. In particular, its intended use is in the method return position only, not as method parameters, fields, or local variables. Also possibly rationale for not Serializable, etc. However, a brief, crisp statement of its intended use (and not much else) is probably called for here.

See

http://stackoverflow.com/a/23464794/1441122

http://stackoverflow.com/a/24564612/1441122

and related for source material.

(Also add notes or references to OptionalInt etc.)