Provide a utility to check API Annotations docs

A utility to check API Annotations was provided in
https://git.haskell.org/ghc.git/commitdiff/43751b2436f370d956d8021b3cdd3
eb77801470b

This commit had poor documentation.

This patch improves the output generated by the utility as well as
supplying better documentation

Test Plan: ./validate

Reviewers: simonpj, austin, bgamari

Reviewed By: austin, bgamari

Subscribers: thomie, mpickering

Differential Revision: https://phabricator.haskell.org/D1397

GHC Trac Issues: #10917

2 files changed, 103 insertions, 16 deletions

diff --git a/utils/check-api-annotations/Main.hs b/utils/check-api-annotations/Main.hs
index 7dc2eb3f77..20e6aa0ca2 100644
--- a/utils/check-api-annotations/Main.hs
+++ b/utils/check-api-annotations/Main.hs
@@ -7,6 +7,7 @@ import DynFlags
 import Outputable
 import ApiAnnotation
 import System.Environment( getArgs )
+import System.Exit
 import qualified Data.Map as Map
 import qualified Data.Set as Set
 
@@ -19,7 +20,7 @@ main = do
 
 testOneFile :: FilePath -> String -> IO ()
 testOneFile libdir fileName = do
-       ((anns,cs),p) <- runGhc (Just libdir) $ do
+       ((anns,_cs),p) <- runGhc (Just libdir) $ do
                         dflags <- getSessionDynFlags
                         _ <- setSessionDynFlags dflags
                         let mn =mkModuleName fileName
@@ -33,9 +34,6 @@ testOneFile libdir fileName = do
 
        let sspans = Set.fromList $ getAllSrcSpans (pm_parsed_source p)
 
-           problems = filter (\(s,_a) -> not (Set.member s sspans))
-                             $ getAnnSrcSpans (anns,cs)
-
            exploded = [((kw,ss),[anchor])
                       | ((anchor,kw),sss) <- Map.toList anns,ss <- sss]
 
@@ -45,17 +43,20 @@ testOneFile libdir fileName = do
                                -> not (any (\a -> Set.member a sspans) anchors))
                               exploded'
 
-       putStrLn "---Problems---------------------"
-       putStrLn (intercalate "\n" [showAnns $ Map.fromList $ map snd problems])
-       putStrLn "---Problems'--------------------"
-       putStrLn (intercalate "\n" [pp $ Map.fromList $ map fst problems'])
-       putStrLn "--------------------------------"
-       putStrLn (intercalate "\n" [showAnns anns])
+           problems'' = filter (\((a,_),_) -> a /= AnnEofPos) problems'
 
-    where
-      getAnnSrcSpans :: ApiAnns -> [(SrcSpan,(ApiAnnKey,[SrcSpan]))]
-      getAnnSrcSpans (anns,_) = map (\a@((ss,_),_) -> (ss,a)) $ Map.toList anns
+       putStrLn "---Problems (should be empty list)---"
+       putStrLn (intercalate "\n" [pp $ Map.fromList $ map fst problems''])
+       putStrLn "---Annotations-----------------------"
+       putStrLn "-- SrcSpan the annotation is attached to, AnnKeywordId,"
+       putStrLn "--    list of locations the keyword item appears in"
+       -- putStrLn (intercalate "\n" [showAnns anns])
+       putStrLn (showAnns anns)
+       if null problems''
+          then exitSuccess
+          else exitFailure
 
+    where
       getAllSrcSpans :: (Data t) => t -> [SrcSpan]
       getAllSrcSpans ast = everything (++) ([] `mkQ` getSrcSpan) ast
         where
@@ -64,11 +65,12 @@ testOneFile libdir fileName = do
 
 
 showAnns :: Map.Map ApiAnnKey [SrcSpan] -> String
-showAnns anns = "[\n" ++ (intercalate "\n"
+showAnns anns = "[\n" ++ (intercalate ",\n"
    $ map (\((s,k),v)
-              -> ("(AK " ++ pp s ++ " " ++ show k ++" = " ++ pp v ++ ")\n"))
+              -- -> ("(AK " ++ pp s ++ " " ++ show k ++" = " ++ pp v ++ ")\n"))
+              -> ("((" ++ pp s ++ "," ++ show k ++"), " ++ pp v ++ ")"))
    $ Map.toList anns)
-    ++ "]\n"
+    ++ "\n]\n"
 
 pp :: (Outputable a) => a -> String
 pp a = showPpr unsafeGlobalDynFlags a
diff --git a/utils/check-api-annotations/README b/utils/check-api-annotations/README
index 7c2815a403..fcadc50ff6 100644
--- a/utils/check-api-annotations/README
+++ b/utils/check-api-annotations/README
@@ -16,3 +16,88 @@ In a test Makefile
   $(CHECK_API_ANNOTATIONS) "`'$(TEST_HC)' $(TEST_HC_OPTS) --print-libdir | tr -d '\r'`" FileToParse.hs
 
 See examples in (REPO_HOME)/testsuite/tests/ghc-api/annotations/Makefile
+
+
+Description of operation
+------------------------
+
+The programme is called with the name of a haskell source file.
+
+It uses the GHC API to load and parse this, and extracts the API annotations.
+
+These are of the form
+
+    Map.Map ApiAnnKey [SrcSpan]
+
+where
+
+    type ApiAnnKey = (SrcSpan,AnnKeywordId)
+
+So an annotation is a key comprising the parent SrcSpan in the ParsedSource
+together with an AnnKeywordId, and this maps to a list of locations where the
+specific keyword item occurs in the original source.
+
+The utility extracts all SrcSpans in the ParsedSource, and makes sure that for
+every ApiAnnKey the SrcSpan is actually present in the final ParsedSource. This
+is to ensure that when a given parser production is postprocessed anywhere along
+the line the relevant SrcSpan is not discarded, thus detaching the annotation
+from the final output.
+
+It also provides a list of each ApiAnnKey and the corresponding source
+locations, so these can be checked against the original source for correctness.
+
+Example
+-------
+
+Test10255.hs in the ghc-api/annotations tests has the following source
+
+------------------------------
+1:{-# LANGUAGE ScopedTypeVariables #-}
+2:module Test10255 where
+3:
+4:import Data.Maybe
+5:
+6:fob (f :: (Maybe t -> Int)) =
+7:  undefined
+------------------------------
+
+The output of this utility is
+
+------------------------------------------------------------------------
+---Problems (should be empty list)---
+[]
+---Annotations-----------------------
+-- SrcSpan the annotation is attached to, AnnKeywordId,
+--    list of locations the keyword item appears in
+[
+((Test10255.hs:1:1,AnnModule), [Test10255.hs:2:1-6]),
+((Test10255.hs:1:1,AnnWhere), [Test10255.hs:2:18-22]),
+((Test10255.hs:4:1-17,AnnImport), [Test10255.hs:4:1-6]),
+((Test10255.hs:4:1-17,AnnSemi), [Test10255.hs:6:1]),
+((Test10255.hs:(6,1)-(7,11),AnnEqual), [Test10255.hs:6:29]),
+((Test10255.hs:(6,1)-(7,11),AnnFunId), [Test10255.hs:6:1-3]),
+((Test10255.hs:(6,1)-(7,11),AnnSemi), [Test10255.hs:8:1]),
+((Test10255.hs:6:5-27,AnnCloseP), [Test10255.hs:6:27]),
+((Test10255.hs:6:5-27,AnnOpenP), [Test10255.hs:6:5]),
+((Test10255.hs:6:6-26,AnnDcolon), [Test10255.hs:6:8-9]),
+((Test10255.hs:6:11-26,AnnCloseP), [Test10255.hs:6:26]),
+((Test10255.hs:6:11-26,AnnOpenP), [Test10255.hs:6:11]),
+((Test10255.hs:6:12-18,AnnRarrow), [Test10255.hs:6:20-21]),
+((Test10255.hs:6:12-25,AnnRarrow), [Test10255.hs:6:20-21]),
+((<no location info>,AnnEofPos), [Test10255.hs:8:1])
+]
+------------------------------------------------------------------------
+
+To interpret this, firstly the problems list is empty, so there are not
+annotations that do not appear in the final AST.
+
+Secondly, the list of annotations and locations can be checked against the test
+source code to ensure that every AnnKeywordId does in fact appear.
+
+It will return a zero exit code if the list of problems is empty, non-zero
+otherwise.
+
+Note: In some cases, such as T10269 in the ghc-api/annotations tests the list is
+non-empty, due to postprocessing of the parsed result. In general this should
+only happen for an `AnnVal` and if it does the actual annotations provided need
+to be inspected to check that an equivalent annotation is provided.