Community
Participate
Working Groups
I2003-11-19 1) Create an anonymous inner class like this: new WindowAdapter() { /* (non-Javadoc) * @see java.awt.event.WindowAdapter#windowClosing(java.awt.event.WindowEvent) */ public void windowClosing(WindowEvent e) { dispose(); } } If you have the compiler set up to report javadoc problems, it complains about missing javadoc. 2) observe: you get a quickfix saying "Add javadoc comment". 3) accept the quickfix. 4) observe: the added comment is this: /* (non-Javadoc) * @see java.awt.event.WindowAdapter#windowClosing(java.awt.event.WindowEvent) */ Note that this is not javadoc (i.e. the error remains).
Additional note: if the method is not an override, you get the (correct) javadoc comment added.
Martin, please invetigate. This is something we might want to fix for M5, depending on other bugs we have.
It would be better if jdt core does not complain about missing Javadoc if the method overrides a method from base class. Such methods inherit the Javadoc from the method they override.
This is an area where we know we have to improve. We need to figure what's the proper way to delegate Javadoc spec. Should we also process non Javadoc ? Or rather consider a true Javadoc with @{inheritedDoc}, or something else...
My personal feeling goes to: /** {@inheritDoc} */ (see bug 45782) instead of /* (non-Javadoc) @see... */. This solution would have several advantages: 1) the comment would be still a Javadoc comment 2) there would not have any text duplication 3) minimize work while refactoring and insure that the link would be always accurate Note that this tag and all other inlined tags {@...} are not currently supported by the compiler, but could be the next step to do... If we agree on this proposal, then this bug would be put back to jdt-ui in order to change the generated comment and jdt-core (in fact me, I guess) would have to work to fix bug 45782.
{@inheritDoc} is a Javadoc 1.4 tag. I agree it's definitly nicer than the (non- javadoc) comments, but we can't force people to use the Javadoc 1.4 comment tags. If you use the 1.2 and 1.3 Javadoc command you will get errors if your comment has this tag (and moreover, you don't inherit the ccomment anymore) I think the compiler can find out if a method overrides another method. So don't warn for missing javadoc in these cases (Because they are not really missing!).
Still it should check that the reference is valid in the non-Javadoc, which means we'd have to parse all comments instead of just Javadoc (this is why I would likely make it only a 1.4 thing). However the suggestion to not complain in inherited code is well-taken. We could offer this as an option, as we do for other diagnosis.
*** Bug 47686 has been marked as a duplicate of this bug. ***
The initial example is in an anonymous class. This is a special case which is fixed with bug 47132... Martin, For all other types than local, we have a solution now that bug 47339 is fixed. So, instead of using current generated comment for overriden methods: /** */ public class X implements Comparable { /*(non-Javadoc) * @see java.lang.Comparable#compareTo(java.lang.Object) */ public int compareTo(Object o) { return 0; } } we can now use: /** */ public class X implements Comparable { /** * @see java.lang.Comparable#compareTo(java.lang.Object) */ public int compareTo(Object o) { return 0; } } The compiler will no longer complain about missing parameters...:) So, if you agree with this proposal which do not use Javadoc 1.4 tag, I would assign this bug to you on jdt-ui component in order to change the generated comment
After having discussed with Martin and Philippe, final agreement would be to introduce a new option for the compiler in order to let user deciding whether to get errors/warnings in overriden methods. Fix for this bug is ready but we need to synchronize with JDT-UI for release. See also bug 46854.
Martin, Here's the new compiler option for this functionality: * COMPILER / Reporting Missing Javadoc Comment on Overriden Method * When enabled, the compiler will signal cases where overriden method has no javadoc comment. * The severity of the problem is controlled with option "org.eclipse.jdt.core.compiler.problem.invalidJavadoc". * - option id: "org.eclipse.jdt.core.compiler.problem.missingJavadoc" * - possible values: { "enabled", "disabled" } * - default: "disabled" As we need to be synchronized to release this change, I'll send you a JDT-Core jar file in order to have this bug and bug 46854 fixes and prepare corresponding change in JDT-UI to be able to display the new compiler options. I assign the bug to you to follow the work about this. When you'll be ready, then please reassign the bug to me and we'll release together at this time... Thanks
Fixed. See bug 46854 for more details...
Verified for 3.0M6
