Community
Participate
Working Groups
Build ID: 20090621-0832 Steps To Reproduce: 1. Create a Javadoc link to a package, e.g. {@link java.util.zip}. 2. Under Window, Preferences, Java, Compiler, Javadoc, ensure that: a) "Process Javadoc comments" is checked. b) "Malformed Javadoc comments:" is set to "Warning". c) "Validate tag arguments..." is checked. 3. Observe that the created Javadoc link reports an invalid "Javadoc: Invalid reference" warning as a "Java Problem". It is valid per the Javadoc specification, and is properly linked when running the javadoc tool. More information: This is a new issue to Eclipse 3.5. It is not reproducible under Eclipse 3.4.2 (M20090211-1700). Switching between versions on the same workspace causes the issue to disappear and reappear. Issue is also reproducible in a new workspace. Seems similar to, but a separate issue from bug 101139. Reporting with "major" severity as this results in warnings being incorrectly reported for Java projects where there were previously none. Turning off the Javadoc validation preference may be a work-around, but prevents validation of the many other Javadoc links being used. Leaving as-is may cause other warnings to be missed or buried, including more serious non-Javadoc warnings.
I have the same problem and totaly agree with Mark. This is really nasty in my project because I get lots of wrong warnings and I got used to fight these yellow triangles. Besides 3.5 also invented bug #252120 that also creates tons of wrong warnings.
*** Bug 284333 has been marked as a duplicate of this bug. ***
Created attachment 143244 [details] Proposed Patch Fix with tests added. Also added part of the fix to the bug 283413 - To warn about Java elements referred without their qualified names. http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#seesearchorder "Search order for @see - the Javadoc tool will process a @see tag that appears in a source file (.java), package file (package.html or package-info.java) or overview file (overview.html). In the latter two files, you must fully-qualify the name you supply with @see. In a source file, you can specify a name that is fully-qualified or partially-qualified."
Fred, Could you please review this patch?
As I already said in bug 211504, the Javadoc tools reports a warning for such a reference, e.g. generating the doc for the following class: /** * {@link java.util.zip} */ public class Test { } will give the following warning in the console: Test.java:4: warning - Tag @link: reference not found: java.util.zip Test.java:4: warning - Tag @link: reference not found: java.util.zip Hence, we should not avoid these kind of warning otherwise some users may complain that our compiler does not warn them on possible error while generating the documentation. The only thing we can do now, is to add a new compiler preferences to let user disabling this warning...
Frederic - please clarify your reference to bug 211504 - it doesn't appear to be related. (Guessing a typo?) Please also note that in your example (comment #5), the warning is only given because no link was provided to resolve the JDK classes to. Running javadoc as the following gives no error: javadoc -link http://java.sun.com/javase/6/docs/api/ Test.java I believe that the Javadoc specification is correct, and that javadoc tool is properly following the spec. Eclipse, however, is currently generating this warning prematurely. It cannot consider this to be an "invalid reference" without knowledge of the link URLs. These link URLs do not appear to be available to Eclipse until the "Generate Javadoc" wizard page from Export / Javadoc. For a simple fix, Eclipse should not be generating this warning. Hopefully this is something that could be included in 3.5.1 and the next 3.6 milestone. For an extended fix, Eclipse could check the link URLs before generating this warning. However, there are a few issues here: 1) Even though the selection of "referenced archives and projects to which links should be generated" isn't available until the Javadoc wizard is run (and presumably, not stored for use outside of the time that the Javadoc wizard is run), Eclipse should assume that all links configured on the classpath are valid and available for linking if a Javadoc location is configured for that classpath entry. 2) Eclipse currently only supports a "Javadoc URL" _OR_ "Javadoc in archive" per classpath entry. Javadoc generation requires URLs. However, many projects may be configured with "Javadoc in archive" for performance and/or offline development. Eclipse also does not currently keep the details necessary to support the "-linkoffline" javadoc parameter. Given these complexities, I can understand if such an "extended fix" isn't available until 3.6 or later. However, as supported by Jörg Hohwiller in comment #1, the "simple fix" is important to have as soon as possible. If the generation of this warning is enabled by a preference option, that might be a good idea to support the "pre-3.5" and now the new "3.5" functionality.
(In reply to comment #6) > Frederic - please clarify your reference to bug 211504 - it doesn't appear to > be related. (Guessing a typo?) > Yes, defintely a typo, sorry for that. You should read bug 211054 instead... > Please also note that in your example (comment #5), the warning is only given > because no link was provided to resolve the JDK classes to. Running javadoc as > the following gives no error: > > javadoc -link http://java.sun.com/javase/6/docs/api/ Test.java > > I believe that the Javadoc specification is correct, and that javadoc tool is > properly following the spec. > Hmm, good point. I didn't know this javadoc option. So, I agree that the compiler cannot afford whether it will be used or not while generating the doc, hence the control has to be loosen and the warning removed... > Eclipse, however, is currently generating this warning prematurely... If you want this fix for 3.5.1, there's no other option than the simple fix (in fact the patch proposed by Jay). Adding a new functionality is not possible in the maintenance stream which must not have any API change...
Agreed on all points from comment #7. Can the patch from Jay please be reviewed and targeted for inclusion in 3.5.1? (We essentially need to undo the change made in bug 211054.) I do not actually even see the need for working on the "extended fix". If it is to be worked on, it should probably be a separate effort and a separate bug. Someone else should open this if they see the need. In general, the issue of potentially invalid Javadoc references is probably better handled by the tool responsible for Javadoc generation. This could be the Javadoc tool, the Eclipse Javadoc export wizard, Apache Ant, or Apache Maven (all of which usually result in targeting the JDK's javadoc tool). Thanks!
Jay, your patch looks good to fix the problem. However, I wonder if it's a good idea to add a silent fix for another bug (bug 283413). I think in this case, it's definitely necessary to split the two fixes, because the fix for this bug will surely be a 3.5.1 candidate although it may not be the case for the other bug... So, please redo a patch with only the fix for this bug and ask Olivier to review it for 3.5.1 acknowledgment. Then, add a new bug for the other issue (referring to bug 283413) and add a patch to it... Thanks
Created attachment 144802 [details] Updated patch Removed the fix related to bug 283413 from the patch and resubmitting the new patch. Also raised a new bug 286918 for this. Olivier, can you please see if this one can go into 3.5.1?
Comment on attachment 144802 [details] Updated patch Patch looks good to me.
Jay, please prepare a patch for R3_5_maintenance branch (do not forget to update copyrights comment date) and attach it to the bug (even if it's the same than the HEAD one). Thanks
Comment on attachment 144802 [details] Updated patch Jay, please update copyrights date to 2009 and repost the patch, thanks
+1 for 3.5.1.
Created attachment 144949 [details] Updated patch for HEAD Updated the Copyright statement. This patch is for HEAD
Created attachment 144950 [details] Updated patch for 3.5.1 Patch for 3.5 maintenance
In fact RC2 is only next week not this one, hence no PMC approval is necessary prior releasing this bug...
Comment on attachment 144949 [details] Updated patch for HEAD Patch looks good.
Comment on attachment 144950 [details] Updated patch for 3.5.1 Patch looks good.
Released HEAD patch for 3.6M2 Released R3_5_maintenance patch for 3.5.1
Thank you everyone! If anyone could help review bug 282891 for inclusion into 3.5.1 as well, it'd be appreciated. It is very similar to this bug in that it also results in false warnings being generated, but is focused on the actual Java code rather than Javadoc. There is already a patch present and released to HEAD. (I was already looking at packaging and maintaining patched .jar's to fix these issues for my team under 3.5. If 3.5.1 can fix this before 3.6, it will make things much easier.) Thanks again!
Verified for 3.5.1RC2 using M20090826-1100.
Verified.
Verified for 3.6M2 using I20090915-0100.
