Community
Participate
Working Groups
3.0 RC3 /** * @return */ int get(); It should warn about the missing argument for @return tag if compiler option to process Javadoc is enabled.
There's no expected reference after @return tag. See javadoc tool 1.4 spec (http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#@return): @return description Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values. This tag is valid only in a doc comment for a method. For more details, see http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@return.
I did not say anything about a reference but there must be a description as you can read in your comment ;-) javadoc tool issues a warning if the description is missing. You can find such warnings in Eclipse SDK's javadoc log.
It seems that I've read the spec in diagonal... But the fact that description was mandatory seemed not really obvious for me. I read it with your help ;) and now agree that we *should* have a non-empty description here...
deferred post 3.0
Candidate for 3.0.1
Fixed. In this case, compiler now reports following warning: "Javadoc: Missing return type description" [jdt-core-internal] Change done in AbstractCommentParser.parseComment(int,int). Also add methods verifyCharsAfterReturnTag(int). Test cases added in JavadocTestMixed and ASTConverterJavadocTest.
Released in HEAD.
Pardon my interjection, but I am a little confused here. This bug has a target milestone of 3.0.1 but the fix has only been released to HEAD. Will this be fixed in 3.0.1?
Yes it was. "Fixed" in comment 6 means "Fixed and released in R3_0_maintenance stream". I never precise explicitely stream in wich I fix the bug assuming this is always bug target default stream. For 3.0.1 target this is R3_0_maintenance stream and for 3.1 this is HEAD stream. So, you do not need to rely on comments to know whether the bug is fixed for 3.0.1 or not. Look at target and status/resolution: 3.0.1 + RESOLVED/FIXED means that this bug is fixed for 3.0.1 version... Comment 7 was only to signal that the bug was also fixed for 3.1 version.
Sorry, I missed that as I read the bug. Many others had been explicitly posting "released to maintenance stream" comments. As you point out that comment is not really required since the fields indicate it, but I had grown accustom to the message.
This warning is rather inconsistent in I200408241200: (1) There's only a warning when the @return tag is the last tag in the javadoc. (2) There's no warning for missing descriptions for @param, @exception, etc. . I would expect to get warnings everywhere or nowhere, but not only for some tags. This example produces no warning at all: /** * @param param * @return * @throws IOException */ public int m(int param) throws IOException { throw new IOException(Integer.toString(param)); }
Verified for 3.0.1 RC1
