[jdt-core-dev] leading and trailing comments and whitespace for AST/DOM

[Jim_des_Rivieres@xxxxxxxxxx]

We're trying to decide how to deal with leading and trailing whitespace 
and comments for AST/DOM nodes, and we need your input.

ref: http://bugs.eclipse.org/bugs/show_bug.cgi?id=28268

Summary of where we are right now:
- source range extends from 1st character of 1st real token through
last character of last real token matched by grammar rule for node type;
leading whitespace and comments, and trailing whitespace, comments are
NOT INCLUDED in source range with the exception of Javadoc comments
- for BodyDeclarations, the Javadoc comment is treated like a token and
is represented by a Javadoc node
- Statement.get/setLeadingComment allows for a single comment before
the statement; however, AST.parseCompilationUnit has never associated
leading comments with any statement nodes it creates

So where do we go from here? At the very least, we should
(1) clarify this contract in the API spec
(2) delete (deprecate) Statement.get/setLeadingComment

This would at least gives us a minimal, consistent, approach for 
leading and trailing comments. The question is: is it worthwhile doing 
more?
The general approach to date has been that AST/DOM clients interested in
finer-grained lexical issues should rescan the source in the vicinity of
the construct to find what they're interesting in. This is reasonably
straightforward, given org.eclipse.jdt.core.compiler.IScanner and accurate
and consistent source ranges for all nodes and ancestors

We could add a second, "extended" source range to certain node types
like statements, body declarations, import declarations, and package 
declarations that would
"round up" to the "natural" source line boundary to better align with what 
a human author would
consider the source range for a construct. 

Q: If the API had this, would clients use it (given that many of them 
already
have their own scanners and have to do this sort of thing other places 
too)? If yes, what are
"natural" boundaries that this API should recognize?

Your input would be appreciated.

Thanks,
jeem