Bug 73348 - [Javadoc] Missing description for return tag is not always warned
Summary: [Javadoc] Missing description for return tag is not always warned
Status: VERIFIED FIXED
Alias: None
Product: JDT
Classification: Eclipse Project
Component: Core (show other bugs)
Version: 3.0   Edit
Hardware: PC Windows XP
: P3 minor (vote)
Target Milestone: 3.0.2   Edit
Assignee: Frederic Fusier CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2004-09-07 03:18 EDT by Markus Keller CLA
Modified: 2005-03-10 05:10 EST (History)
0 users

See Also:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Markus Keller CLA 2004-09-07 03:18:13 EDT 
I200409011200, from bug 68017:

"Malformed Javadoc" warnings are rather inconsistent:

(1)  There's only a warning for "Missing return type description" 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
in certain positions.

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));
	}
Comment 1 Frederic Fusier CLA 2004-09-07 04:43:39 EDT 
Ok for point 1), I'll have a fix soon.
For point 2), the problem here is that compiler does not care about text after
tag name, param name or references. Scan text has a cost and make it for all
tags can be time consuming.
Looking at spec for Javadoc (again) it's not specified that description is
mandatory or should be written for @param, @see and @throws tags.
So, at my point of view this point should be optional (for example: "Javadoc tag
has to have a description").
As this sounds more than a requirement, I will open another bug for this point
and of course change the summary of this one...
Comment 2 Frederic Fusier CLA 2004-09-07 04:46:05 EDT 
This bug is only for following issue:

Compiler provides no warning for following missing description on @return tag:
/**
 * @return
 * @see Object
 */
public int m() {
}
Comment 3 Frederic Fusier CLA 2004-09-13 07:25:39 EDT 
Fixed and released in HEAD.
This bug will be targeted for 3.0.2 when available and released in
R3_0_maintenance stream after 3.0.1 is shipped...

Now empty return tag description are properly identified even if tag is not the
last one.
Note that in following specific case:
	/**
	 * @return
	 *         int
	 * @see Object
	 */
	public int m() {
compiler will not raise any warning as description has been correctly written...

[jdt-core-internal]
Changes done in JavadocReturnStatement and AbstractCommentParser classes +
JavadocParser.pushText(int,int) method.
Test cases added in JavadocTestMixed and ASTConverterJavadocTest.
Comment 4 Frederic Fusier CLA 2004-09-20 05:06:20 EDT 
Fixed and released in R3_0_maintenance stream.
Bug Target still needs to be set to 3.0.2 when it will be available...
Comment 5 Frederic Fusier CLA 2004-09-21 09:26:37 EDT 
Setting target to 3.1 M2 while waiting for 3.0.2 one...
Comment 6 David Audel CLA 2004-09-23 10:57:48 EDT 
Verified in I200409230100.
Comment 7 David Audel CLA 2004-09-23 11:18:00 EDT 
Reopen to change statuc
Comment 8 David Audel CLA 2004-09-23 11:18:34 EDT 
Change status to Fixed

Verified in I200409230100.
Comment 9 Frederic Fusier CLA 2004-09-24 05:17:50 EDT 
Finally set status as VERIFIED.
We'll only change target when fix will be definitely put in R3_0_maintenance
stream...
Comment 10 Frederic Fusier CLA 2005-01-26 12:49:00 EST 
Candidating fix for 3.0.2 release (not committed yet)
Comment 11 David Audel CLA 2005-03-10 05:10:49 EST 
Verified with M20050216