--- a/jdk/src/java.base/share/classes/java/util/OptionalDouble.java Thu Apr 20 11:06:28 2017 -0700
+++ b/jdk/src/java.base/share/classes/java/util/OptionalDouble.java Thu Apr 20 11:40:57 2017 -0700
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -37,7 +37,7 @@
* <p>Additional methods that depend on the presence or absence of a contained
* value are provided, such as {@link #orElse(double) orElse()}
* (returns a default value if no value is present) and
- * {@link #ifPresent(java.util.function.DoubleConsumer) ifPresent()} (performs
+ * {@link #ifPresent(DoubleConsumer) ifPresent()} (performs
* an action if a value is present).
*
* <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
@@ -45,6 +45,12 @@
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code OptionalDouble} may have unpredictable results and should be avoided.
*
+ * @apiNote
+ * {@code OptionalDouble} is primarily intended for use as a method return type where
+ * there is a clear need to represent "no result." A variable whose type is
+ * {@code OptionalDouble} should never itself be {@code null}; it should always point
+ * to an {@code OptionalDouble} instance.
+ *
* @since 1.8
*/
public final class OptionalDouble {
@@ -110,6 +116,12 @@
* If a value is present, returns the value, otherwise throws
* {@code NoSuchElementException}.
*
+ * @apiNote
+ * The methods {@link #orElse(double) orElse} and
+ * {@link #orElseGet(DoubleSupplier) orElseGet}
+ * are generally preferable to this method, as they return a substitute
+ * value if the value is absent, instead of throwing an exception.
+ *
* @return the value described by this {@code OptionalDouble}
* @throws NoSuchElementException if no value is present
* @see OptionalDouble#isPresent()