Bug 231796

Summary: [formatter] @throws tag description is not indented using @param preference when there's a syntax error
Product: [Eclipse Project] JDT Reporter: Eric Jodet <eric_jodet>
Component: CoreAssignee: Frederic Fusier <frederic_fusier>
Status: VERIFIED FIXED QA Contact:
Severity: normal    
Priority: P3 CC: amj87.iitr, jerome_lanneluc, philippe_mulet, srikanth_sankaran
Version: 3.4   
Target Milestone: 3.6 M1   
Hardware: PC   
OS: Windows XP   
Whiteboard:
Attachments:
Description Flags
Proposed patch none

Description Eric Jodet CLA 2008-05-13 09:21:59 EDT 
Version: 3.4.0
Build id: I20080510-2000

while verifying fix for bug 229954,  found that the @throws tag behave as the @param tag regarding javadoc formatting preferences.

Using the new formatter (Build id: I20080510-2000):
/**
 * @throws import org.eclipse.core.runtime.CoreException if there's a marker
 * problem
 */

Using the old formatter (Build id: M20070921-1145):
/**
 * @throws import
 *             org.eclipse.core.runtime.CoreException if there's a marker
 *             problem
 */

Note: with the new formatter, no new line is added after the @throws reference,
whereas, with the old formatter, the @throws tag is handled like a @param tag
(this is confirmed by switching corresponding preference: when New line after
@param tags preference is disabled, no new line is added when formatting the
above javadoc)
Comment 1 Frederic Fusier CLA 2008-05-13 11:41:34 EDT 
Note that in fact the new comment formatter output is:
/**
 * @throws import org.eclipse.core.runtime.CoreException if there's a marker
 *         problem
 */

The fact is that the @throws reference is syntactically incorrect (the keyword import). In this case, the tag is considered as a normal tag with only text after its name, hence the indentation is only applied for root tag, not for @param tag...
Comment 2 Frederic Fusier CLA 2008-05-14 05:25:53 EDT 
Change the summary to reflect the real problem.
Comment 3 Frederic Fusier CLA 2008-05-14 09:44:19 EDT 
Created attachment 100171 [details]
Proposed patch

This consists to accept all tokens while parsing qualified name reference in comment parsers. The compiler still continues to report an error but now stores the token identifier for the reference instead of returning null.

The point is that it was already done for some tokens as int, void, float, etc... but not for all other tokens only made of alphabetic characters. So, the basic behavior is not modified, just slightly changed to accept all tokens which could be used as identifiers by text parser (as FormatterCommentParser or DocCommentParser).
Comment 4 Frederic Fusier CLA 2008-05-14 10:37:14 EDT 
Jerome, as new formatter behavior is different than the old one on this point, do you think we should put this fix into RC1?
Comment 5 Jerome Lanneluc CLA 2008-05-14 11:55:07 EDT 
I would prefer to defer as this scenario is very rare
Comment 6 Frederic Fusier CLA 2009-06-26 05:50:09 EDT 
Released for 3.6M1 in HEAD stream.
Comment 7 Ayushman Jain CLA 2009-08-03 08:27:39 EDT 
Verified for 3.6M1 using build I20090802-2000