Community
Participate
Working Groups
In the example below, the Javadoc tool complaines about the missing qualification, but the JDT compiler doesn't. public class IntroduceParameterObjectDescriptor { public static class Parameter { /** * The position in the new method signature depends on the * position in the array passed to * {@link IntroduceParameterObjectDescriptor#setParameters(Parameter[])} */ public int getIndex() { return 0; } } } Should be {@link IntroduceParameterObjectDescriptor#setParameters(IntroduceParameterObjectDescriptor.Parameter[])}
(In reply to comment #0) this difference of behavior can be observed with the 1.4.2 Javadoc Tool (Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_15-b02)) The problem is not present at 1.5 or 1.6 level.
So are you saying this was a bug in javadoc tool which got resolved in 1.5/1.6 ? If so, pls try to find bug entry in bugparade.
(In reply to comment #2) Correct Philippe. At the time I wrote comment #1, I tried to find corresponding issue in the bug database, without success. As per a new search, I found several fixed candidates which could explain the difference of behavior observed between versions: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4976957 Other ones: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4686734 http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4464323 Steps to reproduce: - Have a new Java project containing the code below public class IntroduceParameterObjectDescriptor { public static class Parameter { /** * The position in the new method signature depends on the * position in the array passed to * {@link IntroduceParameterObjectDescriptor#setParameters(Parameter[])} * {@link IntroduceParameterObjectDescriptor#setParameters(IntroduceParameterObjectDescriptor.Parameter[])} */ public int getIndex() { return 0; } } public void setParameters(Parameter[] params) { } } - Project --> Generate Javadoc... - keep defaults With the 1.4.2 JRE, 2 warnings: warning - Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor warning - Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor With the 1.6 JRE, no warning. Martin, may you please have a go and try?
Oh, I trust you. So I guess we would have to make it a configurable option if the compiler warns about unqualified inner types in Javadoc. It's still important to have this as not everybody wants to use the latest JDK version and the missing warning already caused us several rebuilds in the Eclipse builds.
(In reply to comment #4) A new preference might not be necessary, if we only intend to mimic the Javadoc tool behavior. We could decide to raise a warning or not depending on JDK level (that is, raise a warning when level < 1.5) Philippe?
I don't think we should conclude from the source compliance to the behaviour of the Javadoc tool used. It's no problem to use a Javadoc command of a 1.6 SDK to generate documentation for 1.4 projects. It's also not clear how Javadoc implementations from other VM vendors (IBM, BEA) behave. Maybe they already fixed the problem or have not done so yet in 1.5 or 1.6.
My understanding is that it is a bug in Sun's Javadoc tool found in the 1.4.2 JDK. The 1.5 and 1.6 JDKs don't have this problem. And as Marting said, other vendors may not even have this bug. So I don't think it is worth adding a new option to be bug compatible with JDK1.4.2. We already have too many options. It is too bad that we use a buggy Javadoc tool for Eclipse builds, but we don't want to impact every Eclipse users just to avoid breaking Eclipse builds (btw how many were broken by this ?)
I believe the 'bug' (better call it a behavior) existed in all JDK versions until 1.5. So adding support for this makes sense. I didnt't investigate here but its possible that other Javadoc tool vendors still warn on qualified inner types, even in 1.5 and 1.6. I think we 5 or more rebuilds because of such problems. I'm sure Olivier knows more as usually he has to run after these bugs. I doubt that adding that option takes more than half a day. I also believe the option fits nicely in the Javadoc page: Report unqualified references to inner types. So lets please fill this gap now.
The question really is do we want to be bug compatible or not. My vote is no since this is a demonstrated bug in some implementation (like it seems here).
See also bug 175839. We need to resolve both the same way (in fact they are treated as dup by Sun). Maybe we can convince releng to use 'javadoc' tool from 5.0 or IBM 1.4 - but first we'd need to figure out the differences.
Using Eclipse SDK Version: 3.3.0 Build id: I20070821-0800 Observed behavior summary 1.4.2 Level Eclipse - compliance 1.4: no warning Sun JDK 1.4.2: 1 warning (Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor) IBM JDK 1.4.2: 1 warning (Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor) 5.0 Level Eclipse - compliance 5.0: no warning Sun JDK 1.5: no warning IBM JDK 1.5: no warning JRockit 1.5: no warning
I still get the problem in 1.5 and 1.6. I wonder, what did we do different? I used the Javadoc wizard with the different Javadoc commands and I also tried the command line. SUN jdk 1.2.2: javadoc: warning - d.IntroduceParameterObjectDescriptor.Parameter.getIndex(): Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor SUN jdk 1.3.1: javadoc: warning - d.IntroduceParameterObjectDescriptor.Parameter.getIndex(): Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor IBM 1.3.1 javadoc: warning - d.IntroduceParameterObjectDescriptor.Parameter.getIndex(): Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor IBM 1.4.2 C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor Sun 1.5.0_05 C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor Sun 1.5.0_10 C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor Sun 1.6.0_01 C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor Sun 1.6.0_02 C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor Sun 1.7.0-ea C:\workspaces\runtime-workspace\JUnit\src\d\IntroduceParameterObjectDescriptor.java:9: warning - Tag @link: can't find setParameters(Parameter[]) in d.IntroduceParameterObjectDescriptor
Created attachment 77679 [details] [screen shot] Generate Javadoc wizard (In reply to comment #12) Martin, with corresponding project selected and Java editor opened, I use the pull down menu "Project --> Generate Javadoc..." (as per attached screen shot) I then select the path to the javadoc.exe I wish to use. I keep the default settings and click the Finish button. I had another quick go with Sun 1.5 and 1.6, to confirm the results posted in comment #11: warning are only raised when using javadoc 1.4.2, though no warning in Eclipse (which is the issue at hand).
Created attachment 77695 [details] screenshot What's the exact versions of your JDK's?
(In reply to comment #14) Sun java version "1.4.2_15" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_15-b02) Java HotSpot(TM) Client VM (build 1.4.2_15-b02, mixed mode) java version "1.5.0_12" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_12-b04) Java HotSpot(TM) Client VM (build 1.5.0_12-b04, mixed mode) java version "1.6.0_03-ea" Java(TM) SE Runtime Environment (build 1.6.0_03-ea-b01) Java HotSpot(TM) Client VM (build 1.6.0_03-ea-b01, mixed mode) IBM java version "1.4.2" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2) Classic VM (build 1.4.2, J2RE 1.4.2 IBM Windows 32 build cndev-20040524 (JIT ena bled: jitc)) java version "1.5.0" Java(TM) 2 Runtime Environment, Standard Edition (build pwi32dev-20070511 (SR5)) IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Windows XP x86-32 j9vmwi3223-2007042 6 (JIT enabled) J9VM - 20070420_12448_lHdSMR JIT - 20070419_1806_r8 GC - 200704_19) JCL - 20070511
Eric, can you confirm Martin's findings i.e. current (i.e. not early access) 1.6 and older 1.5 shows the bug. Also 1.7 seens to have the bug. What does JRocket 1.4 do?
(In reply to comment #16) Dani, had a go and tried with various "current" versions, no way I could reproduce the behavior observed by Martin :-( May be we're not using the same source code. Martin, may you please provide me with IntroduceParameterObjectDescriptor.java?
>Martin, may you please provide me with IntroduceParameterObjectDescriptor.java? The code from comment 0.
(In reply to comment #18) that's what I suspected. Then, our test cases are different. If I copy/paste the code from comment #0 to a new Java project (with javadoc comment validation on), I get a warning: Javadoc: The method setParameters(IntroduceParameterObjectDescriptor.Parameter[]) is undefined for the type IntroduceParameterObjectDescriptor In a same way, if I use the Javadoc tool (any version), I get a similar warning: warning - Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor As far as I can see in comment #0, this is true that there is no setParameters method in IntroduceParameterObjectDescriptor class, hence we have an unsatisfied link. In order to get rid of this warning, irrelevant for the issue at hand (in comment #0, Martin complained "the Javadoc tool complaines about the missing qualification but the JDT compiler doesn't"), I created the missing method as shown in comment #3. Which clears the warning in the Java editor. But any javadoc tool < 5.0 will still complain about the missing reference: warning - Tag @link: can't find setParameters(Parameter[]) in IntroduceParameterObjectDescriptor Martin, may you please confirm that if you use the fixed code as shown in comment #3, you get the same behavior as described in the above comment? If this is the case, then the fix would consist in taking the compliance into account, to raise a warning when < 5.0
Oh, you're right. I should use the fixed version... Sorry for that! 1.4.2: warning 1.5.0_10: no warning 1.6.0_02: no warning 1.7.0-ea: no warning
(In reply to comment #20) no pb. So, agreed on expected behavior after fixing this one would be to raise a warning only when compliance < 5.0?
Yep.
(In reply to comment #21) > (In reply to comment #20) > no pb. > So, agreed on expected behavior after fixing this one would be to raise a > warning only when compliance < 5.0? > Agreed as well. Just check that JDK 1.3.1 has the bug also. If it doesn't, then the condition would be to raise a warning when compliance == 1.4
(In reply to comment #23) Once work around for bug 202572 applied, same issue with the 1.3.1 javadoc tool. So, this confirms the expected behavior (raise a warning only when compliance < 5.0)
Created attachment 77878 [details] [proposed patch + test case] on top v810 - all jdt.core tests OK Flag unqualified referenced type when this type is defined in an inner class, and Compliance level < 5.0 in order to conform with observed javadoc tool behavior
(In reply to comment #25) Frederic, Jerome, Olivier: please review proposed patch
(In reply to comment #26) Patch looks good to me, so +1 for this patch.
+1
(In reply to comment #26) > (In reply to comment #25) > Frederic, Jerome, Olivier: please review proposed patch > Patch looks good: +1
Released for 3.4M3 in HEAD stream
Verified for 3.4M3 using I20071029-0010 build.
*** Bug 238020 has been marked as a duplicate of this bug. ***
