Bug 25206

Summary:	DOM/AST: Statement.setLeadingComment specification is inconsistent with the JLS
Product:	[Eclipse Project] JDT	Reporter:	Olivier Thomann <Olivier_Thomann>
Component:	Core	Assignee:	Jim des Rivieres <jeem>
Status:	VERIFIED FIXED	QA Contact:
Severity:	normal
Priority:	P3	Keywords:	api, readme
Version:	2.0
Target Milestone:	2.1 M3
Hardware:	PC
OS:	All
Whiteboard:

Description Olivier Thomann

2002-10-22 13:22:47 EDT

The JLS specifies that a line comment has to end with a line break. The
specification of the DOM/AST considers as valid a line comment without the
ending line break.
This is related to bug 23096.

Comment 1 Jim des Rivieres

2002-10-22 18:18:07 EDT

The specification Statement.get/setLeadingComment is unclear. The prose
says that the comments contain the comment delimiters, but the examples
show end-of-line comments without line terminators. The 2.0 implementation
did the latter. The JLS clearly states that end-of-line comments include
the line terminator, so it more consistent to include them than to omit
them.

The spec has been clarified to use standard (JLS 3.7) terminology
and state that and end-of-line comment string includes the line
terminator. The implementation has been brought into line with
this revised spec. This is a minor breaking change for clients that
followed the examples. Due to a 2.0 bug in AST.parseCompilationUnit, 
statement nodes never have a leading comment; this means the probability
is low that actual clients will be broken.

This API change should be documented in the 2.1 release notes.

The revised specification for Statement.setLeadingComment now reads:
* Sets or clears the leading comment string. The comment
* string must include the starting and ending comment delimiters,
* and any embedded linebreaks.
*
* A leading comment is a comment that appears before the statement.
* It may be either a traditional comment or an end-of-line comment.
* Traditional comments must begin with "/&#42;, may contain line breaks,
* and must end with "&#42;/. End-of-line comments must begin with "//",
* must end with a line delimiter (as per JLS 3.7), and must not contain
* line breaks.
*
* Examples:
* setLeadingComment("/&#42; traditional comment &#42;/");  // correct
* setLeadingComment("missing comment delimiters");  // wrong
* setLeadingComment("/&#42; unterminated traditional comment ");  // wrong
* setLeadingComment("/&#42; broken\n traditional comment &#42;/");  // correct
* setLeadingComment("// end-of-line comment\n");  // correct
* setLeadingComment("// end-of-line comment without line terminator");  // 
wrong
* setLeadingComment("// broken\n end-of-line comment\n");  // wrong

Comment 2 Olivier Thomann

2002-10-23 10:30:51 EDT

Fixed and released in 2.1 stream.

Comment 3 David Audel

2002-11-13 09:58:13 EST

Verified.

Comment 4 Jim des Rivieres

2003-02-26 17:37:25 EST

The 2.1 compatibility release notes say that these methods have been 
deleted/deprecated (bug 29176).