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
