diff options
| author | Alan Zimmerman <alan.zimm@gmail.com> | 2015-01-19 08:15:18 -0600 |
|---|---|---|
| committer | Austin Seipp <aseipp@pobox.com> | 2015-01-23 07:18:04 -0600 |
| commit | 5b7a79780b709f4a9d1c110bb786bae1031d1614 (patch) | |
| tree | 77608fe69623b484118b7a67db2661511b84ab1c /compiler/parser/ApiAnnotation.hs | |
| parent | 3a7a30d765d272f10b150c28dcc28726b513b091 (diff) | |
| download | haskell-wip/api-annot-tweaks-7.10.tar.gz | |
API Annotations documentation update, parsing issue, add example testwip/api-annot-tweaks-7.10
Summary:
Add a reference note to each AnnKeywordId haddock comment so GHC
developers will have an idea why they are there.
Add a new test to ghc-api/annotations to serve as a template for other
GHC developers when they need to update the parser. It provides output
which checks that each SrcSpan that an annotation is attached to
actually appears in the `ParsedSource`, and lists the individual
annotations. The idea is that a developer writes a version of this
which parses a sample file using whatever syntax is changed in
Parser.y, and can then check that all the annotations come through.
Depends on D538
Test Plan: ./validate
Reviewers: simonpj, hvr, austin
Reviewed By: austin
Subscribers: thomie, jstolarek
Differential Revision: https://phabricator.haskell.org/D620
(cherry picked from commit 851ed7211fb18fea938be84c99b6389f6762b30d)
Diffstat (limited to 'compiler/parser/ApiAnnotation.hs')
| -rw-r--r-- | compiler/parser/ApiAnnotation.hs | 16 |
1 files changed, 11 insertions, 5 deletions
diff --git a/compiler/parser/ApiAnnotation.hs b/compiler/parser/ApiAnnotation.hs index 60f917222f..e8ad8ea879 100644 --- a/compiler/parser/ApiAnnotation.hs +++ b/compiler/parser/ApiAnnotation.hs @@ -17,9 +17,9 @@ import qualified Data.Map as Map import Data.Data -{- Note [Api annotations] - ~~~~~~~~~~~~~~~~~~~~~~ - +{- +Note [Api annotations] +~~~~~~~~~~~~~~~~~~~~~~ In order to do source to source conversions using the GHC API, the locations of all elements of the original source needs to be tracked. The includes keywords such as 'let' / 'in' / 'do' etc as well as @@ -66,8 +66,8 @@ This is done in the lexer / parser as follows. The PState variable in the lexer has the following variables added -> annotations :: [(ApiAnnKey,SrcSpan)], -> comment_q :: [Located Token], +> annotations :: [(ApiAnnKey,[SrcSpan])], +> comment_q :: [Located AnnotationComment], > annotations_comments :: [(SrcSpan,[Located AnnotationComment])] The first and last store the values that end up in the ApiAnns value @@ -115,6 +115,9 @@ This adds an AnnLet annotation for 'let', an AnnIn for 'in', as well as any annotations that may arise in the binds. This will include open and closing braces if they are used to delimit the let expressions. +The wiki page describing this feature is +https://ghc.haskell.org/trac/ghc/wiki/ApiAnnotations + -} -- --------------------------------------------------------------------- @@ -173,6 +176,9 @@ getAndRemoveAnnotationComments (anns,canns) span = -- Comments are only retained if @'Opt_KeepRawTokenStream'@ is set in -- @'DynFlags.DynFlags'@ before parsing. -- +-- The wiki page describing this feature is +-- https://ghc.haskell.org/trac/ghc/wiki/ApiAnnotations +-- -- Note: in general the names of these are taken from the -- corresponding token, unless otherwise noted -- See note [Api annotations] above for details of the usage |