groovy-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Paul King (JIRA)" <>
Subject [jira] [Closed] (GROOVY-4003) Grammar enhancements to preserve documentation in comments
Date Fri, 01 Feb 2019 10:57:00 GMT


Paul King closed GROOVY-4003.
       Resolution: Won't Fix
    Fix Version/s:     (was: 4.x)

> Grammar enhancements to preserve documentation in comments
> ----------------------------------------------------------
>                 Key: GROOVY-4003
>                 URL:
>             Project: Groovy
>          Issue Type: Improvement
>          Components: parser
>    Affects Versions: 1.7.0
>            Reporter: Andy Clement
>            Priority: Major
> 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:
> whilst a diff from that to the 'normal grammar' is here:
> 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
> - use the ONE_NL_KEEP rule instead of the normal newline processing that discards them
> - oh and pull out the Comment type:
> (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!).

This message was sent by Atlassian JIRA

View raw message