Document that we don't forward calls to default methods, except when …

…we do.

Also, standardize on <b> for Warnings.
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=124370400

guava/src/com/google/common/collect/ForwardingBlockingDeque.java

@@ -33,6 +33,10 @@
  * behaviour. In this case, you should override {@code offer} as well, either providing your own
  * implementation, or delegating to the provided {@code standardOffer} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingBlockingDeque}.
+ *
  * <p>
  * The {@code standard} methods are not guaranteed to be thread-safe, even when all of the methods
  * that they depend on are thread-safe.

guava/src/com/google/common/collect/ForwardingCollection.java

@@ -38,6 +38,10 @@
  * override {@code addAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardAddAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingCollection}.
+ *
  * <p>The {@code standard} methods are not guaranteed to be thread-safe, even
  * when all of the methods that they depend on are thread-safe.
  *

guava/src/com/google/common/collect/ForwardingConcurrentMap.java

@@ -27,6 +27,13 @@
  * the backing map as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
+ * <p><b>{@code default} method warning:</b> This class forwards calls to <i>only some</i> {@code
+ * default} methods. Specifically, it forwards calls only for methods that existed <a
+ * href="https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ConcurrentMap.html">before
+ * {@code default} methods were introduced</a>. For newer methods, like {@code forEach}, it inherits
+ * their default implementations. When those implementations invoke methods, they invoke methods on
+ * the {@code ForwardingConcurrentMap}.
+ *
  * @author Charles Fry
  * @since 2.0
  */

guava/src/com/google/common/collect/ForwardingDeque.java

@@ -34,6 +34,10 @@
  * #offer} which can lead to unexpected behavior. In this case, you should
  * override {@code offer} as well.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingDeque}.
+ *
  * @author Kurt Alfred Kluever
  * @since 12.0
  */

guava/src/com/google/common/collect/ForwardingIterator.java

@@ -27,6 +27,13 @@
  * backing iterator as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
+ * <p><b>{@code default} method warning:</b> This class forwards calls to <i>only some</i> {@code
+ * default} methods. Specifically, it forwards calls only for methods that existed <a
+ * href="https://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html">before {@code default}
+ * methods were introduced</a>. For newer methods, like {@code forEachRemaining}, it inherits their
+ * default implementations. When those implementations invoke methods, they invoke methods on the
+ * {@code ForwardingIterator}.
+ *
  * @author Kevin Bourrillion
  * @since 2.0
  */

guava/src/com/google/common/collect/ForwardingList.java

@@ -44,6 +44,10 @@
  * override {@code addAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardAddAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingList}.
+ *
  * <p>The {@code standard} methods and any collection views they return are not
  * guaranteed to be thread-safe, even when all of the methods that they depend
  * on are thread-safe.

guava/src/com/google/common/collect/ForwardingListIterator.java

@@ -27,6 +27,13 @@
  * behavior of the backing iterator as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
+ * <p><b>{@code default} method warning:</b> This class forwards calls to <i>only some</i> {@code
+ * default} methods. Specifically, it forwards calls only for methods that existed <a
+ * href="https://docs.oracle.com/javase/7/docs/api/java/util/ListIterator.html">before {@code
+ * default} methods were introduced</a>. For newer methods, like {@code forEachRemaining}, it
+ * inherits their default implementations. When those implementations invoke methods, they invoke
+ * methods on the {@code ForwardingListIterator}.
+ *
  * @author Mike Bostock
  * @since 2.0
  */

guava/src/com/google/common/collect/ForwardingMap.java

@@ -34,13 +34,17 @@
  * desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingMap} forward
+ * <p><b>Warning:</b> The methods of {@code ForwardingMap} forward
  * <i>indiscriminately</i> to the methods of the delegate. For example,
  * overriding {@link #put} alone <i>will not</i> change the behavior of {@link
  * #putAll}, which can lead to unexpected behavior. In this case, you should
  * override {@code putAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardPutAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingMap}.
+ *
  * <p>Each of the {@code standard} methods, where appropriate, use {@link
  * Objects#equal} to test equality for both keys and values. This may not be
  * the desired behavior for map implementations that use non-standard notions of

guava/src/com/google/common/collect/ForwardingMapEntry.java

@@ -31,7 +31,7 @@
  * backing map entry as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingMapEntry} forward
+ * <p><b>Warning:</b> The methods of {@code ForwardingMapEntry} forward
  * <i>indiscriminately</i> to the methods of the delegate. For example,
  * overriding {@link #getValue} alone <i>will not</i> change the behavior of
  * {@link #equals}, which can lead to unexpected behavior. In this case, you

guava/src/com/google/common/collect/ForwardingMultiset.java

@@ -41,6 +41,10 @@
  * your own implementation, or delegating to the provided {@code standardAdd}
  * method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingMultiset}.
+ *
  * <p>The {@code standard} methods and any collection views they return are not
  * guaranteed to be thread-safe, even when all of the methods that they depend
  * on are thread-safe.

guava/src/com/google/common/collect/ForwardingNavigableMap.java

@@ -33,12 +33,16 @@
  * override one or more methods to modify the behavior of the backing map as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingNavigableMap} forward <i>indiscriminately</i>
+ * <p><b>Warning:</b> The methods of {@code ForwardingNavigableMap} forward <i>indiscriminately</i>
  * to the methods of the delegate. For example, overriding {@link #put} alone <i>will not</i>
  * change the behavior of {@link #putAll}, which can lead to unexpected behavior. In this case, you
  * should override {@code putAll} as well, either providing your own implementation, or delegating
  * to the provided {@code standardPutAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingNavigableMap}.
+ *
  * <p>Each of the {@code standard} methods uses the map's comparator (or the natural ordering of
  * the elements, if there is no comparator) to test element equality. As a result, if the comparator
  * is not consistent with equals, some of the standard implementations may violate the {@code Map}

guava/src/com/google/common/collect/ForwardingNavigableSet.java

@@ -28,12 +28,16 @@
  * override one or more methods to modify the behavior of the backing set as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingNavigableSet} forward <i>indiscriminately</i>
+ * <p><b>Warning:</b> The methods of {@code ForwardingNavigableSet} forward <i>indiscriminately</i>
  * to the methods of the delegate. For example, overriding {@link #add} alone <i>will not</i>
  * change the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you
  * should override {@code addAll} as well, either providing your own implementation, or delegating
  * to the provided {@code standardAddAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingNavigableSet}.
+ *
  * <p>Each of the {@code standard} methods uses the set's comparator (or the natural ordering of
  * the elements, if there is no comparator) to test element equality. As a result, if the
  * comparator is not consistent with equals, some of the standard implementations may violate the

guava/src/com/google/common/collect/ForwardingQueue.java

@@ -35,6 +35,10 @@
  * override {@code offer} as well, either providing your own implementation, or
  * delegating to the provided {@code standardOffer} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingQueue}.
+ *
  * <p>The {@code standard} methods are not guaranteed to be thread-safe, even
  * when all of the methods that they depend on are thread-safe.
  *

guava/src/com/google/common/collect/ForwardingSet.java

@@ -38,6 +38,10 @@
  * override {@code addAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardAddAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingSet}.
+ *
  * <p>The {@code standard} methods are not guaranteed to be thread-safe, even
  * when all of the methods that they depend on are thread-safe.
  *

guava/src/com/google/common/collect/ForwardingSortedMap.java

@@ -33,13 +33,17 @@
  * the backing sorted map as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingSortedMap} forward
+ * <p><b>Warning:</b> The methods of {@code ForwardingSortedMap} forward
  * <i>indiscriminately</i> to the methods of the delegate. For example,
  * overriding {@link #put} alone <i>will not</i> change the behavior of {@link
  * #putAll}, which can lead to unexpected behavior. In this case, you should
  * override {@code putAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardPutAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingSortedMap}.
+ *
  * <p>Each of the {@code standard} methods, where appropriate, use the
  * comparator of the map to test equality for both keys and values, unlike
  * {@code ForwardingMap}.

guava/src/com/google/common/collect/ForwardingSortedMultiset.java

@@ -33,6 +33,10 @@
  * well, either providing your own implementation, or delegating to the provided {@code
  * standardAdd} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingSortedMultiset}.
+ *
  * <p>The {@code standard} methods and any collection views they return are not guaranteed to be
  * thread-safe, even when all of the methods that they depend on are thread-safe.
  *

guava/src/com/google/common/collect/ForwardingSortedSet.java

@@ -32,13 +32,17 @@
  * backing sorted set as desired per the <a
  * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
  *
- * <p><i>Warning:</i> The methods of {@code ForwardingSortedSet} forward
+ * <p><b>Warning:</b> The methods of {@code ForwardingSortedSet} forward
  * <i>indiscriminately</i> to the methods of the delegate. For example,
  * overriding {@link #add} alone <i>will not</i> change the behavior of {@link
  * #addAll}, which can lead to unexpected behavior. In this case, you should
  * override {@code addAll} as well, either providing your own implementation, or
  * delegating to the provided {@code standardAddAll} method.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingSortedSet}.
+ *
  * <p>Each of the {@code standard} methods, where appropriate, uses the set's
  * comparator (or the natural ordering of the elements, if there is no
  * comparator) to test element equality. As a result, if the comparator is not

guava/src/com/google/common/util/concurrent/ForwardingBlockingQueue.java

@@ -28,6 +28,10 @@
  * as desired per the <a href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator
  * pattern</a>.
  *
+ * <p><b>{@code default} method warning:</b> This class does <i>not</i> forward calls to {@code
+ * default} methods. Instead, it inherits their default implementations. When those implementations
+ * invoke methods, they invoke methods on the {@code ForwardingBlockingQueue}.
+ *
  * @author Raimundo Mirisola
  *
  * @param <E> the type of elements held in this collection