RFR: JDK-8186684: Fix broken links in java.base API docs

[Jonathan Gibbons]

Hi Martin,


On 08/23/2017 02:41 PM, Martin Buchholz wrote:
> I would be inclined to "fix the tool first" if it's not too hard.

Both should be fixed. Going back in time, the spec has long said:
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#specifyingname

    If any method or constructor is entered as a name with no
    parentheses, such as |getValue|, and if there is no field with the
    same name, the Javadoc tool will correctly create a link to it, but
    will print a warning message reminding you to add the parentheses
    and arguments. If this method is overloaded, the Javadoc tool will
    link to the first method its search encounters, which is unspecified.

So, the implication is that since forever, the doc comment should have 
used an arg list. I also note, with regret, that that text was lost from 
the latest version of the spec, and that needs to be fixed.

javadoc is at fault for not giving the warning, and if we fixed the tool 
first, we would just get the warnings, and would still have to fix the 
comments.
I note that javadoc specifies that the behavior is partially 
unspecified, which is another reason to fix the doc comments.
I think that there is an issue as to how the lookup should behave when a 
candidate is not being documented.  i.e. #parent when parent is a 
private field and a public method.  How does this interact with the 
-public and -private command line options?

>
> ---
> Shouldn't the below have a proper arglist?
>
> Consider instead
> {@link #add(Object) add(E)}

Good catch/suggestion. Thanks.

>
> Consider fixing the javadoc tool so that one can actually write {@link 
> #add(E)}

Yeah, another enhancement.  Not today: this is just about fixing broken 
links.

> --- old/src/java.base/share/classes/java/util/ArrayDeque.java	2017-08-23 11:36:43.286955464 -0700
> +++ new/src/java.base/share/classes/java/util/ArrayDeque.java	2017-08-23 11:36:43.070945993 -0700
> @@ -293,7 +293,7 @@
>       /**
>        * Inserts the specified element at the end of this deque.
>        *
> -     * <p>This method is equivalent to {@link #add}.
> +     * <p>This method is equivalent to {@link #add()}.
>        *
>        * @param e the element to add
>        * @throws NullPointerException if the specified element is null
> What about all the other ArrayDeque methods below:
>
> ./ArrayDeque.java:296:     * <p>This method is equivalent to {@link #add}.
> ./ArrayDeque.java:483:     * <p>This method is equivalent to {@link 
> #addLast}.
> ./ArrayDeque.java:497:     * <p>This method is equivalent to {@link 
> #offerLast}.
> ./ArrayDeque.java:513:     * <p>This method is equivalent to {@link 
> #removeFirst}.
> ./ArrayDeque.java:527:     * <p>This method is equivalent to {@link 
> #pollFirst}.
> ./ArrayDeque.java:541:     * <p>This method is equivalent to {@link 
> #getFirst}.
> ./ArrayDeque.java:554:     * <p>This method is equivalent to {@link 
> #peekFirst}.
> ./ArrayDeque.java:569:     * <p>This method is equivalent to {@link 
> #addFirst}.
> ./ArrayDeque.java:582:     * <p>This method is equivalent to {@link 
> #removeFirst()}.

I was specifically fixing broken links (see the list in the JBS issue), 
not doing a general cleanup of all references to methods that needed arg 
lists. That cleanup will need to happen when we fix the tool to generate 
the warnings it promises.

Although it is not immediately clear in the webrev, the underlying 
characteristic of all places where I had to add an empty arg list is 
that there was a private field of the same name in scope.

-- Jon