[Git][ghc/ghc][master] 4 commits: Update exactprint docs

Marge Bot (@marge-bot) gitlab at gitlab.haskell.org
Thu May 30 07:00:27 UTC 2024



Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC


Commits:
3c97c74a by Jan Hrček at 2024-05-30T02:58:58-04:00
Update exactprint docs

- - - - -
77760cd7 by Jan Hrček at 2024-05-30T02:58:58-04:00
Incorporate review feedback

- - - - -
87591368 by Jan Hrček at 2024-05-30T02:58:58-04:00
Remove no longer relevant reference to comments

- - - - -
05f4f142 by Jan Hrček at 2024-05-30T02:58:59-04:00
Replace outdated code example

- - - - -


2 changed files:

- compiler/GHC/Parser/Annotation.hs
- compiler/GHC/Types/SrcLoc.hs


Changes:

=====================================
compiler/GHC/Parser/Annotation.hs
=====================================
@@ -485,9 +485,9 @@ instance Outputable AddEpAnn where
 -- ---------------------------------------------------------------------
 
 -- | The exact print annotations (EPAs) are kept in the HsSyn AST for
---   the GhcPs phase. We do not always have EPAs though, only for code
---   that has been parsed as they do not exist for generated
---   code. This type captures that they may be missing.
+--   the GhcPs phase. They are usually inserted into the AST by the parser,
+--   and in case of generated code (e.g. by TemplateHaskell) they are usually
+--   initialized using 'NoAnn' type class.
 --
 -- A goal of the annotations is that an AST can be edited, including
 -- moving subtrees from one place to another, duplicating them, and so
@@ -501,19 +501,19 @@ instance Outputable AddEpAnn where
 --
 -- The 'ann' type parameter allows this general structure to be
 -- specialised to the specific set of locations of original exact
--- print annotation elements.  So for 'HsLet' we have
+-- print annotation elements.  For example
 --
---    type instance XLet GhcPs = EpAnn AnnsLet
---    data AnnsLet
---      = AnnsLet {
---          alLet :: EpaLocation,
---          alIn :: EpaLocation
---          } deriving Data
+-- @
+-- type SrcSpannAnnA = EpAnn AnnListItem
+-- @
+--
+-- is a commonly used type alias that specializes the 'ann' type parameter to
+-- 'AnnListItem'.
 --
 -- The spacing between the items under the scope of a given EpAnn is
 -- normally derived from the original 'Anchor'.  But if a sub-element
 -- is not in its original position, the required spacing can be
--- directly captured in the 'anchor_op' field of the 'entry' Anchor.
+-- captured using an appropriate 'EpaDelta' value for the 'entry' Anchor.
 -- This allows us to freely move elements around, and stitch together
 -- new AST fragments out of old ones, and have them still printed out
 -- in a precise way.
@@ -535,7 +535,7 @@ data EpAnn ann
 -- annotations.
 -- It is also normally used as the reference point for the spacing of
 -- the element relative to its container. If the AST element is moved,
--- that relationship is tracked in the 'anchor_op' instead.
+-- that relationship is tracked using the 'EpaDelta' constructor instead.
 type Anchor = EpaLocation -- Transitional
 
 anchor :: (EpaLocation' a) -> RealSrcSpan
@@ -553,7 +553,7 @@ noSpanAnchor =  EpaDelta (SameLine 0) noAnn
 
 -- ---------------------------------------------------------------------
 
--- | When we are parsing we add comments that belong a particular AST
+-- | When we are parsing we add comments that belong to a particular AST
 -- element, and print them together with the element, interleaving
 -- them into the output stream.  But when editing the AST to move
 -- fragments around it is useful to be able to first separate the
@@ -602,9 +602,9 @@ Note [XRec and Anno in the AST]
 
 The exact print annotations are captured directly inside the AST, using
 TTG extension points. However certain annotations need to be captured
-on the Located versions too.  While there is a general form for these,
-captured in the type SrcSpanAnn', there are also specific usages in
-different contexts.
+on the Located versions too.  There is a general form for these,
+captured in the type 'EpAnn ann' with the specific usage captured in
+the 'ann' parameter in different contexts.
 
 Some of the particular use cases are
 
@@ -615,7 +615,7 @@ to its usage inside a list.
 
 See the section above this note for the rest.
 
-The Anno type family maps the specific SrcSpanAnn' variant for a given
+The Anno type family maps to the specific EpAnn variant for a given
 item.
 
 So
@@ -639,7 +639,7 @@ data TrailingAnn
   | AddCommaAnn   { ta_location :: EpaLocation }  -- ^ Trailing ','
   | AddVbarAnn    { ta_location :: EpaLocation }  -- ^ Trailing '|'
   | AddDarrowAnn  { ta_location :: EpaLocation }  -- ^ Trailing '=>'
-  | AddDarrowUAnn { ta_location :: EpaLocation }  -- ^ Trailing  "⇒"
+  | AddDarrowUAnn { ta_location :: EpaLocation }  -- ^ Trailing '⇒'
   deriving (Data, Eq)
 
 instance Outputable TrailingAnn where
@@ -730,7 +730,7 @@ data NameAnn
       nann_close     :: EpaLocation,
       nann_trailing  :: [TrailingAnn]
       }
-  -- | Used for @(,,,)@, or @(#,,,#)#
+  -- | Used for @(,,,)@, or @(#,,,#)@
   | NameAnnCommas {
       nann_adornment :: NameAdornment,
       nann_open      :: EpaLocation,
@@ -769,7 +769,7 @@ data NameAnn
       nann_trailing  :: [TrailingAnn]
       }
   -- | Used when adding a 'TrailingAnn' to an existing 'LocatedN'
-  -- which has no Api Annotation (via the 'EpAnnNotUsed' constructor.
+  -- which has no Api Annotation.
   | NameAnnTrailing {
       nann_trailing  :: [TrailingAnn]
       }
@@ -893,7 +893,7 @@ So for the first example we have
 
   binds: fa = 1 , fb = 'c'
   sigs:  fa :: Int, fb :: Char
-  tags: SigTag, BindTag, SigTag, BindTag
+  tags: SigDTag, BindTag, SigDTag, BindTag
 
 so we draw first from the signatures, then the binds, and same again.
 
@@ -901,7 +901,7 @@ For the second example we have
 
   binds: fb = 'c', fa = 1
   sigs:  fa :: Int, fb :: Char
-  tags: SigTag, SigTag, BindTag, BindTag
+  tags: SigDTag, SigDTag, BindTag, BindTag
 
 so we draw two signatures, then two binds.
 


=====================================
compiler/GHC/Types/SrcLoc.hs
=====================================
@@ -908,15 +908,12 @@ mkSrcSpanPs (PsSpan r b) = RealSrcSpan r (Strict.Just b)
 -- ---------------------------------------------------------------------
 
 
--- | The anchor for an @'AnnKeywordId'@. The Parser inserts the
+-- | The anchor for an exact print annotation. The Parser inserts the
 -- @'EpaSpan'@ variant, giving the exact location of the original item
 -- in the parsed source.  This can be replaced by the @'EpaDelta'@
 -- version, to provide a position for the item relative to the end of
 -- the previous item in the source.  This is useful when editing an
--- AST prior to exact printing the changed one. The list of comments
--- in the @'EpaDelta'@ variant captures any comments between the prior
--- output and the thing being marked here, since we cannot otherwise
--- sort the relative order.
+-- AST prior to exact printing the changed one.
 
 data EpaLocation' a = EpaSpan !SrcSpan
                     | EpaDelta !DeltaPos !a



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/d040133546a1b2754539e0942987233209c1eced...05f4f1420be27f2852b61f8c348c742961e210d5

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/d040133546a1b2754539e0942987233209c1eced...05f4f1420be27f2852b61f8c348c742961e210d5
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240530/bd3ed4fe/attachment-0001.html>


More information about the ghc-commits mailing list