RFR [9] 8039527: Broken links in ConcurrentMap javadoc (original) (raw)

Chris Hegarty chris.hegarty at oracle.com
Thu Apr 10 10:27:50 UTC 2014

On 10 Apr 2014, at 11:03, David Holmes <david.holmes at oracle.com> wrote:

Looks good to me too Chris.

Thanks for looking at this David. Unfortunately I pushed before receiving this mail, so you are not listed as a reviewer on the changeset,

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. :(

Right. This could be considered an issue with javadoc. It is difficult to say if relative hrefs should be resolved against the subtypes package hierarchy. At the very least a bug against the javadoc tool should be filed so that we can get final clarification on expected behaviour. I will do this.

-Chris.

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 - * (optional) + * (optional) * @throws NullPointerException if the specified key is null and this map * does not permit null keys - * (optional) + * (optional) */ boolean containsKey(Object key); @@ -177,10 +177,10 @@ * specified value * @throws ClassCastException if the value is of an inappropriate type for * this map - * (optional) + * (optional) * @throws NullPointerException if the specified value is null and this * map does not permit null values - * (optional) + * (optional) */ 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 - * (optional) + * (optional) * @throws NullPointerException if the specified key is null and this map * does not permit null keys - * (optional) + * (optional) */ 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 - * (optional) + * (optional) * @throws NullPointerException if the specified key is null and this * map does not permit null keys - * (optional) + * (optional) */ 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 - * (optional) + * (optional) * @throws NullPointerException if the specified key is null and this map * does not permit null keys - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws NullPointerException if function or a replacement value is null, * and this map does not permit null keys or values - * (optional) + * (optional) * @throws IllegalArgumentException if some property of a replacement value * prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the key or value is of an inappropriate * type for this map - * (optional) + * (optional) * @throws NullPointerException if the specified key or value is null, * and this map does not permit null keys or values - * (optional) + * (optional) * @throws IllegalArgumentException if some property of the specified key * or value prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the key or value is of an inappropriate * type for this map - * (optional) + * (optional) * @throws NullPointerException if the specified key or value is null, * and this map does not permit null keys or values - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map - * (optional) + * (optional) * @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 - * (optional) + * (optional) * @throws ClassCastException if the class of the specified key or value * prevents it from being stored in this map - * (optional) + * (optional) * @throws NullPointerException if the specified key is null and this map * does not support null keys or the value or remappingFunction is * null -Chris.

More information about the core-libs-dev mailing list