RFR [9] 8039527: Broken links in ConcurrentMap javadoc

[David Holmes]

Looks good to me too Chris.

But I can't help wonder if there is a design flaw in javadoc here, as 
this means you should never use relative links in any doc element that 
might be inherited. Which almost reduces to never use relative links. :(

David

On 10/04/2014 12:07 AM, Chris Hegarty wrote:
> java.util.concurrent.ConcurrentMap contains several broken links to
> Collection.html#optional-restrictions. See
>
> http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ConcurrentMap.html
>
>
> The issue is caused by the use of '{@inheritDoc}' in many '@throws'
> definitions. ConcurrentMap's superType Map, is in the java.util package.
> Map has documentation references to Collection.html, which is in the
> same package as Map, java.util, but since ConcurrentMap is not in
> java.util it needs different relative links, or better still links
> relative to the docRoot.
>
> Trivial diffs inline:
>
> diff --git a/src/share/classes/java/util/Map.java
> b/src/share/classes/java/util/Map.java
> --- a/src/share/classes/java/util/Map.java
> +++ b/src/share/classes/java/util/Map.java
> @@ -157,10 +157,10 @@
>        *         key
>        * @throws ClassCastException if the key is of an inappropriate
> type for
>        *         this map
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key is null and
> this map
>        *         does not permit null keys
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        */
>       boolean containsKey(Object key);
>
> @@ -177,10 +177,10 @@
>        *         specified value
>        * @throws ClassCastException if the value is of an inappropriate
> type for
>        *         this map
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified value is null and
> this
>        *         map does not permit null values
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        */
>       boolean containsValue(Object value);
>
> @@ -204,10 +204,10 @@
>        *         {@code null} if this map contains no mapping for the key
>        * @throws ClassCastException if the key is of an inappropriate
> type for
>        *         this map
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key is null and
> this map
>        *         does not permit null keys
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        */
>       V get(Object key);
>
> @@ -264,10 +264,10 @@
>        *         is not supported by this map
>        * @throws ClassCastException if the key is of an inappropriate
> type for
>        *         this map
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key is null and this
>        *         map does not permit null keys
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        */
>       V remove(Object key);
>
> @@ -577,10 +577,10 @@
>        * {@code defaultValue} if this map contains no mapping for the key
>        * @throws ClassCastException if the key is of an inappropriate
> type for
>        * this map
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key is null and
> this map
>        * does not permit null keys
> -     * (<a href="Collection.html#optional-restrictions">optional</a>)
> +     * (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default V getOrDefault(Object key, V defaultValue) {
> @@ -659,13 +659,13 @@
>        * values
>        * @throws ClassCastException if a replacement value is of an
> inappropriate
>        *         type for this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if function or a replacement value
> is null,
>        *         and this map does not permit null keys or values
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws IllegalArgumentException if some property of a
> replacement value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ConcurrentModificationException if an entry is found to be
>        * removed during iteration
>        * @since 1.8
> @@ -726,16 +726,16 @@
>        *         if the implementation supports null values.)
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the key or value is of an
> inappropriate
>        *         type for this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key or value is
> null,
>        *         and this map does not permit null keys or values
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws IllegalArgumentException if some property of the
> specified key
>        *         or value prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default V putIfAbsent(K key, V value) {
> @@ -772,13 +772,13 @@
>        * @return {@code true} if the value was removed
>        * @throws UnsupportedOperationException if the {@code remove}
> operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the key or value is of an
> inappropriate
>        *         type for this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key or value is
> null,
>        *         and this map does not permit null keys or values
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default boolean remove(Object key, Object value) {
> @@ -821,14 +821,14 @@
>        * @return {@code true} if the value was replaced
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of a specified key or
> value
>        *         prevents it from being stored in this map
>        * @throws NullPointerException if a specified key or newValue is
> null,
>        *         and this map does not permit null keys or values
>        * @throws NullPointerException if oldValue is null and this map
> does not
>        *         permit null values
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws IllegalArgumentException if some property of a
> specified key
>        *         or value prevents it from being stored in this map
>        * @since 1.8
> @@ -871,10 +871,10 @@
>        *         if the implementation supports null values.)
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of the specified key or
> value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key or value is
> null,
>        *         and this map does not permit null keys or values
>        * @throws IllegalArgumentException if some property of the
> specified key
> @@ -942,10 +942,10 @@
>        *         is null
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of the specified key or
> value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default V computeIfAbsent(K key,
> @@ -1003,10 +1003,10 @@
>        *         remappingFunction is null
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of the specified key or
> value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default V computeIfPresent(K key,
> @@ -1079,10 +1079,10 @@
>        *         remappingFunction is null
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of the specified key or
> value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @since 1.8
>        */
>       default V compute(K key,
> @@ -1157,10 +1157,10 @@
>        *         value is associated with the key
>        * @throws UnsupportedOperationException if the {@code put} operation
>        *         is not supported by this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws ClassCastException if the class of the specified key or
> value
>        *         prevents it from being stored in this map
> -     *         (<a
> href="Collection.html#optional-restrictions">optional</a>)
> +     *         (<a
> href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
>
>        * @throws NullPointerException if the specified key is null and
> this map
>        *         does not support null keys or the value or
> remappingFunction is
>        *         null
>
> -Chris.