Sync back from GHC

src/Language/Haskell/GHC/ExactPrint/ExactPrint.hs

@@ -608,7 +608,7 @@ addComments sortNeeded csNew = do
   cs <- getUnallocatedComments
   debugM $ "addComments:cs" ++ show cs
   -- We can only sort the comments if we are in the first phase,
-  -- were all comments have locations. If any have EpaDelta the
+  -- where all comments have locations. If any have EpaDelta the
   -- sort will fail, so we do not try.
   if sortNeeded && all noDelta (csNew ++ cs)
     then putUnallocatedComments (sort (cs ++ csNew))
@@ -1729,7 +1729,7 @@ data HsModuleImpDecls
     } deriving Data
 
 instance ExactPrint HsModuleImpDecls where
-  -- Use an UnHelpfulSpan for the anchor, we are only interested in the comments
+  -- Use an UnhelpfulSpan for the anchor, we are only interested in the comments
   getAnnotationEntry mid = mkEntry (EpaSpan (UnhelpfulSpan UnhelpfulNoLocationInfo)) [] (EpaComments (id_cs mid))
   setAnnotationAnchor mid _anc _ cs = mid { id_cs = priorComments cs ++ getFollowingComments cs }
      `debug` ("HsModuleImpDecls.setAnnotationAnchor:cs=" ++ showAst cs)

src/Language/Haskell/GHC/ExactPrint/Transform.hs

@@ -367,9 +367,14 @@ pushDeclDP d _dp = d
 
 -- ---------------------------------------------------------------------
 
--- | If we compile in haddock mode we get DocDecls, which we strip out
--- while exact printing. Make sure we do not balance any comments on
--- to them be stripping them out here already.
+-- | If we compile in haddock mode, the haddock processing inserts
+-- DocDecls to carry the Haddock Documentation. We ignore these in
+-- exact printing, as all the comments are also available in their
+-- normal location, and the haddock processing is lossy, in that it
+-- does not preserve all haddock-like comments. When we balance
+-- comments in a list, we migrate some to preceding or following
+-- declarations in the list. We must make sure we do not move any to
+-- these DocDecls, which are not printed.
 balanceCommentsList :: [LHsDecl GhcPs] -> [LHsDecl GhcPs]
 balanceCommentsList decls = balanceCommentsList' (filter notDocDecl decls)