8285368: Overhaul doc-comment inheritance

6376959: Algorithm for Inheriting Method Comments seems to go not as documented
6934301: Support directed inheriting of class comments with @inheritDoc

Reviewed-by: jjg, rriggs, aivanov, smarks, martin

src/java.base/share/classes/java/util/TreeMap.java

@@ -1195,6 +1195,8 @@ public class TreeMap<K,V>
      * {@code Set.remove}, {@code removeAll}, {@code retainAll} and
      * {@code clear} operations.  It does not support the
      * {@code add} or {@code addAll} operations.
+     *
+     * @return {@inheritDoc SortedMap}
      */
     public Set<Map.Entry<K,V>> entrySet() {
         EntrySet es = entrySet;

src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java

@@ -1531,7 +1531,7 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
     // ConcurrentMap methods
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @return the previous value associated with the specified key,
      *         or {@code null} if there was no mapping for the key
@@ -1542,9 +1542,10 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @throws NullPointerException if the specified key is null
+     * @return {@inheritDoc ConcurrentMap}
      */
     public boolean remove(Object key, Object value) {
         if (key == null)
@@ -1553,9 +1554,10 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @throws NullPointerException if any of the arguments are null
+     * @return {@inheritDoc ConcurrentMap}
      */
     public boolean replace(K key, V oldValue, V newValue) {
         if (key == null || oldValue == null || newValue == null)
@@ -1564,7 +1566,7 @@ public class ConcurrentHashMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @return the previous value associated with the specified key,
      *         or {@code null} if there was no mapping for the key

src/java.base/share/classes/java/util/concurrent/ConcurrentSkipListMap.java

@@ -1773,7 +1773,7 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
     /* ------ ConcurrentMap API methods ------ */
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @return the previous value associated with the specified key,
      *         or {@code null} if there was no mapping for the key
@@ -1788,11 +1788,12 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @throws ClassCastException if the specified key cannot be compared
      *         with the keys currently in the map
      * @throws NullPointerException if the specified key is null
+     * @return {@inheritDoc ConcurrentMap}
      */
     public boolean remove(Object key, Object value) {
         if (key == null)
@@ -1801,11 +1802,12 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @throws ClassCastException if the specified key cannot be compared
      *         with the keys currently in the map
      * @throws NullPointerException if any of the arguments are null
+     * @return {@inheritDoc ConcurrentMap}
      */
     public boolean replace(K key, V oldValue, V newValue) {
         if (key == null || oldValue == null || newValue == null)
@@ -1824,7 +1826,7 @@ public class ConcurrentSkipListMap<K,V> extends AbstractMap<K,V>
     }
 
     /**
-     * {@inheritDoc}
+     * {@inheritDoc ConcurrentMap}
      *
      * @return the previous value associated with the specified key,
      *         or {@code null} if there was no mapping for the key

src/java.base/share/classes/java/util/concurrent/LinkedBlockingDeque.java

@@ -628,7 +628,9 @@ public class LinkedBlockingDeque<E>
     }
 
     /**
+     * {@inheritDoc BlockingDeque}
      * @throws NullPointerException if the specified element is null
+     * @return {@inheritDoc BlockingDeque}
      */
     public boolean offer(E e) {
         return offerLast(e);
@@ -665,6 +667,10 @@ public class LinkedBlockingDeque<E>
         return removeFirst();
     }
 
+    /**
+     * {@inheritDoc BlockingDeque}
+     * @return {@inheritDoc BlockingDeque}
+     */
     public E poll() {
         return pollFirst();
     }
@@ -691,6 +697,10 @@ public class LinkedBlockingDeque<E>
         return getFirst();
     }
 
+    /**
+     * {@inheritDoc BlockingDeque}
+     * @return {@inheritDoc BlockingDeque}
+     */
     public E peek() {
         return peekFirst();
     }