Community
Participate
Working Groups
I20050118-1015 Javadoc reference to vararg method also considers non-array type as correct. http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#specifyingname says that in "@see #method(Type, Type,...)", "Type can be a class, interface, array, or primitive". Therefore, I think "@see #print(String[])" is the right reference format. "@see #print(String)" is clearly wrong. public class A { /** * @see #print(String must warn here: no method print(String) * @see #print(String[]) OK * @see #print(String...) correct warning: invalid reference */ public void print(String ... args) { } /** * @see #write(String) correct warning * @see #write(String[]) OK */ public void write(String[] args) { } }
IMO, we should have following warnings (note that javadoc 1.5.0 spec does not help on this point...): public class A { /** * @see #print(String) must warn * @see #print(String[]) must _also_ warn (String[] is _different_ than String...) * @see #print(String...) should be the only valid reference */ public void print(String ... args) { } }
If #print(String...) should be a valid reference, then class MethodRefParameter must be updated to reflect this. Currently, only SingleVariableDeclaration nodes allow to write the variable arity ellipses (...), and MethodRefParameter only has a Type.
Jeem, could you provide feedback on this point? Thanks
From looking at the Javadoc 5.0 spec, there is no special way for referring to a varargs method. Given this, we should not change the MethodRefParameter. So I think the behavior should be: * @see #print(String) - incorrect: there is no method with this signature * @see #print(String[]) - correct - "as good as it gets" * @see #print(String...) - incorrect: syntax error */ public void print(String ... args) { }
ok, thanks. I'll do it that way...
Hmm, I tried this with javadoc.exe from jdk1.5.0, and that one also accepts #print(String...): /** * @see #print(String) javadoc.exe: incorrect * @see #print(String[]) javadoc.exe: correct * @see #print(String...) javadoc.exe: correct */ public void print(String... args) { } Looks like we have a clash between the javadoc "compiler" and its "spec" :-(
Eclipse accepts all of these as references to print(String...): @see #print() @see #print(String) @see #print(String, String) but rejects @see #print(String, Integer) I guess the current implementation considers a javadoc reference like a method invocation, which is not quite correct. A javadoc reference seems to be a "raw" reference to a method declaration, where argument types and count must be equal to those of the method's erasure. Given that javadoc.exe and its "spec" are not in sync, I now think that we should follow javadoc.exe's behavior and add a "varargs" property to MethodRef. People will probably find it strange when we mark a reference as invalid, but javadoc.exe happily accepts it. See also bug 83127 comment 4. Jeem, what do you think?
Fixed. Implemented as described by Markus in comment 7. [jdt-core-internal] Modifications done in AbstractCommentParser, DocCommentParser, JavadocParser, JavadocMessageSend and JavadocAllocationExpression. Test case added in JavadocTest_1_5, JavadocTest_1_4 and JavadocTest_1_3
Hm, but now the MethodRef '#print(String...)' has a MethodRefParameter 'String...' whose type claims to be an ArrayType. ArrayType is spec'd to be 'Type [ ]', which does not allow 'String...'. Either Jim's decision of comment 4 should be revised, or '#print(String...)' should be a syntax error. The other change (error on non-array argument types) is fine.
if '#print(String...)' was a syntax error then when wouldn't compliant with Javadoc.exe behavior, and i was what you and Martin wanted to avoid if I've well understood. So, the only solution now is to modify MethodRefParameter to add a variable arity as it was done for SingleVariableDeclaration. Jeem, if you agree then open a new bug. If not then continue argumentation in this one...
In light of comment #7, I take back what I said in comment #4. MethodRefParameter should have a variable arity field like SingleVariableDeclaration. I've entered bug 87845.
Verified in I20050330-0500
