Community
Participate
Working Groups
+++ This bug was initially created as a clone of Bug #73352 +++ With bug 73352, a new feature was added to Eclipse 3.4M3 which allows to specify Window > Preferences > Java > Compiler > Javadoc Malformed Javadoc comments: Warning Missing tag descriptions: Validate all tags The problem with this setting is, that there are some Javadoc tags which usually do not have a description or argument, but still issue a warning: @generated @private Especially the "@generated" tag is problematic since it is generated by EMF. It's a pity if I have to disable the whole "missing description" warning feature just because it overloads my Problems view with rogue warning due to EMF: Javadoc: description expected after @generated I think that the "Missing tag descriptions" warning feature should have a user-editable blacklist of Javadoc tags that it should not check (because users can add their own Javadoc tags and some of these may be designed not to take any description or arguments).
This would require a new option to request a list of 'known' tags. Changing the severity as enhancement as this requires a change in the API. However this is very unlikely that we will be able to provide this by M6 (next week) which is the last milestone for API changes.
What about a hardcoded list in a property file, for a start? - The problem with @generated is really annoying for me. I'm not sure what other tags could make it into that list, put having a file with the single @generated one would be a start.
This would still be an API change since right now the spec says that it considers all tags. So we would have to clarify that a property file is used. I'm afraid we currently don't have the resources to implement this. In the meantime, a workaround would be to filter the warnings in the Problems view: Configure Contents > Description > Doesn't contain > @generated. Would that work for you?
Wouldn't it be better to only check for description on the Javadoc tags of the built-in tags? (the tags we know) For user defined tags like @private or @generated we shouldn't make any assumtions. I think we should change the spec on the API (it was added in 3.4) to say that all 'standard' tags are validated. We can fix the code then also in M7, if this is complicated.
This sounds like a good suggestion. It's better to only check what's known rather than making assumptions about the general case. As a definition of what is a standard tag, I'd propose taking all the block tags from http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#javadoctags Tag Introduced in JDK/SDK @author 1.0 @deprecated 1.0 @exception 1.0 @param 1.0 @return 1.0 @see 1.0 @serial 1.2 @serialData 1.2 @serialField 1.2 @since 1.1 @throws 1.2 @version 1.0 With respect to the inline tags, does the code even check the inline tags currently? There are five which do expect an argument: {@code} 1.5 {@link} 1.2 {@linkplain} 1.4 {@literal} 1.5 {@value} 1.4 and two which do not take any argument: {@docRoot} 1.3 {@inheritDoc} 1.4
Trying to set the priority for this enhancement, can you tell me if the workaround suggested in comment 3 works for you?
(In reply to comment #4) +1. Should fix the API for M6 (implementation can wait until M7). (In reply to comment #5) > With respect to the inline tags, does the code even check the inline tags > currently? If it does, it has to accept both {@value} and {@value package.class#field} (since 1.5).
(In reply to comment #3) > meantime, a workaround would be to filter the warnings in the Problems view: > Configure Contents > Description > Doesn't contain > @generated. > Would that work for you? This is a nice idea, but the problem with this workaround is that I'm often using the text filter of the problems view for filtering other kinds of messages. Now it looks like since recently I'm able to save away my various kinds of filters for the problems view, but still I feel it's kinda clumsy having to switch. Also, the workaround works for one tag ("@generated") only. It fails when I have multiple different kinds of tags that I'd need to filter away, because the text filter in the problems view does not support patterns or regular expressions (which would be a really nice enhancement, hint hint). So - the workaround would be kind of ok in my concrete situation but I think that not changing the API specification to only apply to known tags is the right solution for now, and fixing the code later on.
(In reply to comment #8) Oops that was a typo -- I'm *in favor* of changing the API spec now and fixing it afterwards.
(In reply to comment #7) > (In reply to comment #5) > > With respect to the inline tags, does the code even check the inline tags > > currently? > Yes inline tags are also checked. > If it does, it has to accept both {@value} and {@value package.class#field} > (since 1.5). > The compiler accept {@value} for all compliances but only on static field javadoc comments and {@value package.class#field} on all javadoc comments but only if the compliance is >= 1.5... But @value is not expected to have any description, so this bug does not seem relevant for this tag... Do not mix reference and description.
I think the right approach would be to add a new option: JavaCore#COMPILER_PB_MISSING_JAVADOC_TAG_DESCRIPTION_ALL_STANDARD_TAGS Reusing JavaCore#COMPILER_PB_MISSING_JAVADOC_TAG_DESCRIPTION_ALL_TAGS doesn't feel like a good idea, since "ALL" really means all tags.
> JavaCore#COMPILER_PB_MISSING_JAVADOC_TAG_DESCRIPTION_ALL_STANDARD_TAGS The new option sounds good. But you should remove the COMPILER_PB_MISSING_JAVADOC_TAG_DESCRIPTION_ALL_TAGS then, since it has only been introduced for 3.4 and is really of little use. When you add support for user-supplied tag names in 3.5 or later, you could then add a fresh option to include those in the validation as well.
> The new option sounds good. But you should remove the > COMPILER_PB_MISSING_JAVADOC_TAG_DESCRIPTION_ALL_TAGS then, since it has only > been introduced for 3.4 and is really of little use. +1. As the bug shows, it doesn't seem that the 'all' option is very practical.
Created attachment 93125 [details] Proposed fix and regression test
Frederic, can you please review the patch?
Created attachment 93146 [details] New proposed fix and regression test Frederic noticed that the inline tags {@code} and {@literal} were not taken into account. Thanks Frederic. This patch fixes this problem and it adds more tests.
Fix and test released for 3.4M6. Entered bug 223553 against JDT/UI to adapt to the new constant.
I was OK with the last patch (I forgot to set the review flag yesterday...)
Verified for 3.4M6 using build I20080324-1300.
In terms of migration, what Strings do I need to change in my .settings/org.eclipse.jdt.core.prefs files? I know that migration between milestones doesn't need to be supported officially, but knowing the stuff that I need to replace would simplify the process for me.
(In reply to comment #20) > In terms of migration, what Strings do I need to change in my > .settings/org.eclipse.jdt.core.prefs files? > > I know that migration between milestones doesn't need to be supported > officially, but knowing the stuff that I need to replace would simplify the > process for me. > The value of org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription option has been changed from 'all_tags' to 'all_standard_tags'
Thanks. I think that this was an important fix, especially taking into account the new Javadoc markup from API Tooling: 1. @noimplement which applies to interfaces 2. @noextend which applies to classes, interfaces and methods 3. @noreference which applies to classes, methods and fields 4. @noinstantiate which applies to classes See http://wiki.eclipse.org/Api_Tooling
