Community
Participate
Working Groups
HEAD public class Try { /** * @since 1.0 */ public void m() { } } class Sub extends Try { /** * @since {@inheritDoc} */ public void m() { } } The {@inheritDoc} tag is only valid - in the main description - in the description of return, @param, @throws, or @exception tags In all other locations in the Javadoc, the tag should be flagged as invalid. I would create a new IProblem id for this problem, and control it with the JavaCore.COMPILER_PB_INVALID_JAVADOC option. For the example above, the Javadoc tool generates this "warning" and aborts: warning - @inheritDoc used but m() does not override or implement any method. java.lang.ClassCastException: com.sun.tools.doclets.internal.toolkit.taglets.SimpleTaglet cannot be cast to com.sun.tools.doclets.internal.toolkit.taglets.InheritableTaglet at com.sun.tools.doclets.internal.toolkit.taglets.InheritDocTaglet.retrieveInheritedDocumentation(InheritDocTaglet.java:108) at com.sun.tools.doclets.internal.toolkit.taglets.InheritDocTaglet.getTagletOutput(InheritDocTaglet.java:134) at com.sun.tools.doclets.internal.toolkit.taglets.TagletWriter.getInlineTagOuput(TagletWriter.java:201)
> I would create a new IProblem id for this problem, and control it with the > JavaCore.COMPILER_PB_INVALID_JAVADOC option. Better yet: Just use IProblem.JavadocUnexpectedTag, like here: class Try { /** * {@inheritDoc} */ void m() {} }
(In reply to comment #1) > > I would create a new IProblem id for this problem, and control it with the > > JavaCore.COMPILER_PB_INVALID_JAVADOC option. > > Better yet: Just use IProblem.JavadocUnexpectedTag, like here: > > class Try { > /** > * {@inheritDoc} > */ > void m() {} > } > Agreed, we already use this warning while flagging {@inheritDoc} used elsewhere than a method or constructor javadoc comment...
Some observations: 1. The message from Javadoc is somewhat odd : "warning - @inheritDoc used but m() does not override or implement any method.". m() is overriding super's m(), but the code is still flawed as pointed out by submitter since @inheritDoc cannot be used with @since 2. It seems that due to a bad side effect of the fix for bug#51606 we are not consistent in reporting missing tags as shown below. (Missing javadoc tags - warning Visibility - default Ignore overriding and implementing methods - unchecked) class Try { /** * * @param m Blah * @param n Blah * @return Blah * */ int m(int m, int n) { return 0;} /** * * @param m Blah * @param n Blah * @return Blah * */ int n(int m, int n) { return 0;} } class Sub extends Try { /** * @return {@inheritDoc} */ int m(int m, int n) { return 0; } /** * * @param m {@inheritDoc} */ int n(int m, int n) { return 0;} } We complain about Sub.n's missing tags while being silent about Sub.m's missing tags. 3. Due probably to the same issue, we don't always complain about @inheritDoc being used in constructors or fields where it is outlawed. 4. Completion proposals contain @inheritDoc where it is illegal.
> 1. The message from Javadoc is somewhat odd I agree, the message is wrong. > 2. It seems that due to a bad side effect of the fix for bug#51606 > we are not consistent in reporting missing tags as shown below. Bug 51606 was not valid, see bug 246850. > We complain about Sub.n's missing tags while being silent about Sub.m's > missing tags. Both Sub.n and Sub.m are not missing any tags (see how javadoc.exe copies tags: http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#inheritingcomments ). See bug 246236 for tag inheritance problems. > 4. Completion proposals contain @inheritDoc where it is illegal. That's bug 194273.
(In reply to comment #4) > > 1. The message from Javadoc is somewhat odd > I agree, the message is wrong. > > 2. It seems that due to a bad side effect of the fix for bug#51606 > > we are not consistent in reporting missing tags as shown below. > Bug 51606 was not valid, see bug 246850. Thanks for citing the related bugs. That does simplify matters since the oddities that I encounted are covered by others defects.
Some more odd behaviors: 1. If a method that doesn't override anything uses {@inheritDoc} we report a single unexpected tag error even when the {@inheritDoc} tag was used several times. 2. If {@inheritDoc} is used in the javadoc for a class or interface or package, we don't complain at all. 3. A tag of the form: @throws {@inheritDoc} results in a Missing class name error.
> 3. A tag of the form: > @throws {@inheritDoc} > results in a Missing class name error. That's fine, since the {@inheritDoc} is not to be interpreted at that location: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@throws expects a 'class-name' there. There are already other bugs where tags are interpreted at spots where they should be treated as plain text (bug 206319, bug 206345).
(In reply to comment #7) > > 3. A tag of the form: > > @throws {@inheritDoc} > > results in a Missing class name error. > > That's fine, since the {@inheritDoc} is not to be interpreted at that location: > http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#@throws > expects a 'class-name' there. > This arguable as there's no error while generating with the Javadoc tool, although there's one if the description is empty... So, there's a difference between the compiler checking and the Javadoc tool behavior. But I agree this way (eclipse reports a problem but Javadoc does not - although it should) is not really a big trouble and we can live with it...
Created attachment 129573 [details] Proposed patch Frederic, could you please review this patch ? Let me know is something is amiss. This patch ensures/verifies that use of {@inheritDoc} triggers a diagnostic if that use is - in the javadoc for a class, package, interface, constructor, field. - not in the main description and also not in any block tag other than @param, @return, @throws or @exception. Also in a non-overriding method, we complain about every use of {@inheritDoc} (and not just only one of them as before).
Created attachment 129679 [details] Revised patch & tests Per Frederic's comments: - split large tests into many smaller ones. - removed needless //$FALL-THROUGH$ markers - effected a couple of (perf) improvements. Fredreic, appreciate your help with committing this patch. TIA.
(In reply to comment #10) > Created an attachment (id=129679) [details] > Revised patch & tests > > > Per Frederic's comments: > > - split large tests into many smaller ones. > - removed needless //$FALL-THROUGH$ markers > - effected a couple of (perf) improvements. > > Fredreic, appreciate your help with committing this patch. > TIA. > Released for 3.5M7 in HEAD stream.
Verified for 3.5M7 using I20090426-2000
