Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 231297

Summary: [formatter] New JavaDoc formatter wrongly split inline tags before reference
Product: [Eclipse Project] JDT Reporter: Frederic Fusier <frederic_fusier>
Component: CoreAssignee: Frederic Fusier <frederic_fusier>
Status: VERIFIED FIXED QA Contact:
Severity: normal    
Priority: P3 CC: daniel_megert, eric_jodet, jerome_lanneluc, Konstantin.Scheglov, Olivier_Thomann, philippe_mulet
Version: 3.4Flags: jerome_lanneluc: review+
Target Milestone: 3.4 RC1   
Hardware: PC   
OS: Windows XP   
Whiteboard:
Bug Depends on: 231263    
Bug Blocks:    

Description Frederic Fusier CLA 2008-05-09 09:42:57 EDT 
Second issue reported initially in bug 231263...
The following simple example:
public class X {

	/**
	 * @return an inline tag: {@link String} inside the description.
	 */
	public String foo() {
		return null;
	}
}

is currently formatted by the new formatter (Eclipse build-in + max length=40):
public class X {

	/**
	 *.@return an inline tag: {@link
	 *.<tab>String} inside the description.
	 */
	public String foo() {
		return null;
	}
}

Although the old formatter formatted it as:
public class X {

	/**
	 *.@return an inline tag:
	 *.........{@link String} inside the
	 *.........description.
	 */
	public String foo() {
		return null;
	}
}

(again, I used points for spaces to make it clearer).

For 3.4, we need to keep the old formatter behavior and see if a preference needs to be added in 3.5 to make the inline tags 'splittable'...
Comment 1 Frederic Fusier CLA 2008-05-09 10:34:30 EDT 
The old formatter rules for inline tag splitting seem to be:
1) Never split references even if they are over the max length
2) Never format the description on the same line than reference
   That means do not replace several consecutive spaces/tabs by one space
3) If the description is on several lines then format the lines after the first 
   one

Some samples to illustrate these rules (all using Eclipse built-in + specific max length formatting options):

First example for rule 1), max length=30:
public class X01 {

	/**
	 * @return tag: {@link java.lang.String}
	 */
	public String foo() {
		return null;
	}
}
is formatted as:
public class X01 {

	/**
	 * @return tag:
	 *         {@link java.lang.String}
	 */
	public String foo() {
		return null;
	}
}
=> the reference is not split although over column 30

Second example for rule 2), max length=40:
public class X02 {

	/**
	 * @return an inline tag: {@link String inline   tag    description}
	 */
	public String foo() {
		return null;
	}
}
is formatted as:
public class X02 {

	/**
	 * @return an inline tag:
	 *         {@link String inline   tag    description}
	 */
	public String foo() {
		return null;
	}
}
=> the description is not split although over column 40 and spaces between words are not changed

Third example for rule 3), including also tabs between words , max length=40:
public class X03 {

	/**
	 * @return an inline tag: {@link String inline   tag    description
	 *     on more than
	 *		one	line      }
	 */
	public String foo() {
		return null;
	}
}
is formatted as:
public class X03 {

	/**
	 * @return an inline tag:
	 *         {@link String inline   tag    description
	 *         on more than one line }
	 */
	public String foo() {
		return null;
	}
}
=> the first line is not formatted (neither split nor reducing spaces) but the two following ones are formatted

Rule 1) seems OK but I would say that 2) and 3) looks a little bit weird.

So, I would propose new rules:
1) never split references (same as old)
2) format inline tag description as root tag descriptions (i.e. allow to split lines and reduce spaces between words to one space)

Konstantin, would these new rules be acceptable for you and would not break too much your existing formatted code?
Comment 2 Konstantin Scheglov CLA 2008-05-09 11:42:30 EDT 
(In reply to comment #1)

> So, I would propose new rules:
> 1) never split references (same as old)
> 2) format inline tag description as root tag descriptions (i.e. allow to split
> lines and reduce spaces between words to one space)
> 
> Konstantin, would these new rules be acceptable for you and would not break too
> much your existing formatted code?
> 

  For me these rules are perfect, because I don't use inline tag descriptions, only references.
  In general they also sound logical.
Comment 3 Frederic Fusier CLA 2008-05-11 14:20:25 EDT 
Jerome, can you please review?

The patch for this bug is the one attached on bug 231263:
https://bugs.eclipse.org/bugs/attachment.cgi?id=99640
Comment 4 Jerome Lanneluc CLA 2008-05-13 12:53:39 EDT 
Reviewed patch with Frederic: +1
Comment 5 Frederic Fusier CLA 2008-05-13 13:21:57 EDT 
Released for 3.4RC1 in HEAD stream.
Comment 6 Eric Jodet CLA 2008-05-14 01:54:21 EDT 
Verified for 3.4RC1 using build I20080513-2000