On 10 Apr 2014, at 11:03, David Holmes <david.hol...@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 >> - * (<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.
