Community
Participate
Working Groups
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'...
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?
(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.
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
Reviewed patch with Frederic: +1
Released for 3.4RC1 in HEAD stream.
Verified for 3.4RC1 using build I20080513-2000
