Details
-
Improvement
-
Status: Closed
-
Major
-
Resolution: Won't Fix
-
1.7.0
-
None
-
None
Description
This enhancement is to cover investigating whether to use some of the groovy eclipse grammar extensions to allow groovy itself to preserve comments (javadoc) and include them in any stubs that are output. I would have liked to spend time extracting them out from the rest of the grammar changes and finishing them off but I don't have time right now. So this is just to get the discussion going.
As linked by Guillaume, the grammar we use now is here:
http://fisheye.codehaus.org/browse/groovy/eclipse/trunk/base/org.codehaus.groovy/src/org/codehaus/groovy/internal/antlr/parser/groovy.g#r18665
whilst a diff from that to the 'normal grammar' is here:
http://fisheye.codehaus.org/browse/groovy/eclipse/trunk/base/org.codehaus.groovy16/src/org/codehaus/groovy/internal/antlr/parser/groovy.g?r1=18665&r2=17587
There are numerous changes in there to improve parser recovery. Meaning that when erroneous syntax is encountered, the parser doesn't crash out, it instead recovers as best it can and continues. Capturing as many errors as possible in a single pass and producing 'correct as we can' output at the end of a parse is important in the IDE. I have not run the groovy tests against this modified grammar to tell if anything in groovy is adversely affected but the changes are 99% in the error handling so hopefully they make no difference in the normal case. (although there is one place where I use 'mark()' in case I need to recover later, not sure how expensive that is)
However, to extract just the portion relating to comments, you need to:
- pull out the comments property plus accessor
- pull out the startComment/endComment logic
- pull out the changes to comment rules (single and multi line) that invoke start/end comment
- use the ONE_NL_KEEP rule instead of the normal newline processing that discards them
- oh and pull out the Comment type:
http://fisheye.codehaus.org/browse/groovy/eclipse/trunk/base/org.codehaus.groovy16/src/org/codehaus/groovy/ast/Comment.java?r=HEAD
(which additionally includes some task tag locator code that may or may not be wanted...)
that would give you enough to preserve comments. At the end of the parse of a file they are available through the accessor 'getComments()', with full positional information.
In an ideal world what would happen is that the parser maintains a 'most recent comment' and on parse processing of any element that could be doc'd, the parse logic would grab that most recent comment and attach it to that element of the ast. It would then null the most recent comment object. This ensures all elements get the right documentation. I didn't have the time to do that and so right now what is available at the end of processing is all the comments and by looking at positions they are associated with the right elements in the Ast (so groovy eclipse can do javadoc hovers). I didn't make the extra changes I am describing here because I couldn't face writing the antlr and it would make the patch much more complicated as every rule that parsed something that could be documented would be changed. (And I have to maintain/apply this patch each time groovy changes!).