Community
Participate
Working Groups
Using 02100800, you cannot get rid of unused imports if the type is referenced inside a javadoc comment. From the compiler point of view, the import is unused, but "Organize imports" doesn't get rid of it. The guilty type is referenced inside a @see tag of a javadoc comment. I will attach a test case asap.
The compiler settings for checking javadoc comments are all disabled. Checking the source indexer, it seems that the javadoc comments are always indexed. They should be indexed only if the compiler settings for javadoc comments are checked. If they are checked, an import should not be reported as unused if there is a reference inside a javadoc comment. The current behavior is not consistent.
Created attachment 7755 [details] Test case 1) Set the compiler settings to report an error on unused imports. Disable all checks for javadoc comments. 2) Import the test case in a java project 3) You should get a compile error in the class A. The import of test.test1.test2.B is unused. 4) Run "Organize imports" and the imports won't go away. 5) Remove the import and run "Organize imports" again. The import is back.
They are indexed all the time, so that if the user toggles the preference later on, we don't have to reindex the project/workspace. However, organize imports should be able to recognize the compiler option, and not include reference from within Javadocs if the user doesn't care about Javadocs. In a similar way, search should offer to discriminate Javadoc references from source code references.
I would say that even if the user cares about malformed or missing javadocs the type references inside a javadoc should never be used by "Organize imports". You never want them as they are not required to compile the code. This leads to "false" errors reported by the compiler concerning the unused imports. "Organize imports" should still be a solution to remove unused imports. This is one of the quickfixes proposed in such a case (the other one is to remove the specified import).
*** Bug 51614 has been marked as a duplicate of this bug. ***
I think references in Javadoc should always be considered, regardless if you enabled warnings or errors for Javadoc tags. Note that I currently set the Javadoc tags problems to 'ignore' as I don't want to deal with it right now, but I will near the final releae when generating Javadoc documentation. But I don't want to touch all my code then to add the imports. Each developper in the team should be able to decide to ignore, warn ect. about Javadoc tag references. Those that have them on ignore would now always remove certain imports resulting in errors with those who enabled the warnings. Javadoc comments are really a part of the Java language. It was always a bug that organize import ignored these references. I think if you don't want such references (and imports and search results), then you should better use normal block comments that Javadoc comments.
Note that there is a open bug that organize import also adds imports for qualified names (bug 51497). I will fix that for M7.
The behavior has to be consistent. Right now it isn't. If an import is tagged as unused, Organize imports should get rid of it or it should not be tagged as unused.
Martin, I don't see why "Organize imports" needs to look inside Javadoc. Even if Javadoc are part of the language in term of documentation, imports are related to source code. You don't "compile" comments. In the test case I provided, I am expecting to get a warning or an error for an unused import. I don't expect "Organize import" to add that import. It is not necessary to compile the code. Therefore it should be removed. So "Organize imports" should not consider the type references inside Javadoc. Only the one in the actual source code.
The Javadoc tool will not be able to resolve the type refs if there is no import, so you get errors there. I guess what you can say that a Java file serve for more than 'just generating code'. It's also for generating documentation, and the imports are used for both thing, there not 'just for code'.
I can understand the argument, but if the imports are used for both the javadoc generation and the compilation, then the compiler should not flag these as unused. To summarize, organize imports is behaving correctly but the compiler is incorrectly marking the imports as unused.
Just another example to illustrate the problem that would show up when we would implement the suggested fix in comment 4: - developer A has javadoc checking enabled and adds imports as they are required for the type in the comment's Javadoc tags. - developer B catched up with that file, but has javadoc checking disabled and sees the import maked as usused. He removed the imports and commits the file - developer A catches up but get errors: Unresolved type in the comment
*** Bug 51497 has been marked as a duplicate of this bug. ***
Re: comment 12. The rule is: If Javadoc check is disabled, the compiler will not resolve any reference in Javadoc, and thus may diagnose certain imports to be unused. If Javadoc check is enabled, then these imports may be used to resolve Javadocs. If user wants to generate Javadoc, then he should care about these, and enable the compiler diagnosis for these. In general, compilers do ignore Javadocs, and thus we certainly do not want to consider them by default. Re: comment 13. This is not different from any other compiler settings. As soon as different teammates diverge, then these issues may arise. Teammates should agree on the proper warning/error level, and likely share preferences.
If we did what Martin suggested, we would end up *always* attempting to resolve Javadoc references, which could unleash various compilation problems: aborting compilation on inconsistent binaries, etc... We should certainly only do so on demand. I think a much better solution would be: NEVER add import for references in Javadoc, but rather qualify them. This way, you avoid the problem entirely. The source is left untouched. You should dissociate the addition of imports for source refs vs. doc refs. In source, it is a style issue. in doc, it can lead to these issues. So, if you want my opinion, you make these 2 settings: - add import for source ref: ENABLED by default - add import for doc ref: DISABLED by default
Moving back to JDT UI. This issue is real, unfortunately by the JLS, the compiler cannot consider doc references. We do it as a courtesy, and then it interferes with the unused import diagnosis. As described earlier, this could be solved during organize imports by avoiding adding import for doc references, since these may interfere when different users don't use the same settings.
I want the option that problems on javadoc ar _not_ reported, but I still get imports to be checked if they are needed in Javadoc comments. Can we add this to the compiler perference page?
This would force the compiler to resolve *all* Javadoc, even though it would silently not surface these problems. This feels confusing. It would rather make more sense to provide filters to hide these.
I think now what we should have is a single flag. 'Enable Javadoc support'. If disabled, Organize import, refactoring, linked rename, search, unused imports, quick fix ect. will not look and work on references in Javadoc comments. If enabled, these features are enabled. If enabled I, a user would like to be able to fine granulary decide which problems in Javadoc tags I want to be reported (exactly as we have it now in the Javadoc compiler pref page) and which not. I can't change oganize imports for now but would prefer if first agree on a consistent story about references in Javadocs.
Talked with Dirk. We agreed on a Javadoc global flag which would determine the behavior for compiler, refactoring, ... Still edging whether search shouldn't still allow a checkbox, as Javadoc would likely be a scope notion as well (the checkbox would default to the value of the global flag?).
Global Javadoc flag sounds good for me. This should not imply too much work to implement it and fix this organize import problem... What about JavaCore.COMPILER_DOC_COMMENT_SUPPORT ?
Sounds good to me.
What about RuntimeExceptions? /***/ public class Test { /** * @throws java.nio.BufferOverflowException if XXX */ void m() { //RT exception could be thrown here } } @@@@ Adding the exception to the method signiture will create also create an import, which will promptly be considered "unused": /***/ public class Test { /** * @throws java.nio.BufferOverflowException if XXX */ void m() throws BufferOverflowException { //RT exception could be thrown here } }
David, that unneeded import comes from bug 51770 which is fixed in M7
Martin, Have you change anything in jdt-ui about this? Using build I200402260800, I cannot reproduce the problem described on initial test case provided by Olivier in comment 3. Instead, the import is always flagged as unused and removed by "Organized import" both when Javadoc options are disabled or enabled...!?
Yes, that was a fix for 51770: The bug was that imports were added for fully qualified type names in Javadoc comments. It seems we changed the topic a bit in this bug report. What's stil open is that /** * @see Vector */ public void foo() { } Adds an import to Vector which is marked as unused. We wnated to have a constint handling. Either no import added or no 'unneeded' warning, depending on the global Javadoc flag.
Fixed. Unused import will be now signaled by compiler only when global option is not set (see bug 52264) whatever other javadoc compiler options values are... [jdt-core-internal] No specific dvpt for this bug, all changes were done for bug 52264... Test cases added in jdt.core.tests.compiler.regression.JavadocTestMixed
Verified in build I200403250010.
