Add Note [Warnings in code generated by Alex]

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

1 files changed, 35 insertions, 7 deletions

diff --git a/compiler/parser/Lexer.x b/compiler/parser/Lexer.x
index 98d167d4dd..01e7de3efd 100644
--- a/compiler/parser/Lexer.x
+++ b/compiler/parser/Lexer.x
@@ -41,20 +41,16 @@
 -- Alex "Haskell code fragment top"
 
 {
--- XXX The above flags turn off warnings in the generated code:
 {-# LANGUAGE BangPatterns #-}
+
+-- See Note [Warnings in code generated by Alex] in compiler/parser/Lexer.x
 {-# OPTIONS_GHC -fno-warn-unused-matches #-}
 {-# OPTIONS_GHC -fno-warn-unused-binds #-}
 {-# OPTIONS_GHC -fno-warn-unused-imports #-}
 {-# OPTIONS_GHC -fno-warn-tabs #-}
 {-# OPTIONS_GHC -fno-warn-missing-signatures #-}
-{-# OPTIONS_GHC -fno-warn-overlapping-patterns #-}
--- The above warning suppression flags are a temporary kludge.
--- While working on this module you are encouraged to remove it and fix
--- any warnings in the module. See
---     http://ghc.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings
--- for details
 
+{-# OPTIONS_GHC -fno-warn-overlapping-patterns #-}
 {-# OPTIONS_GHC -funbox-strict-fields #-}
 
 module Lexer (
@@ -2695,4 +2691,36 @@ isDocComment (ITdocSection      _ _) = True
 isDocComment (ITdocOptions      _)   = True
 isDocComment (ITdocOptionsOld   _)   = True
 isDocComment _ = False
+
+{- Note [Warnings in code generated by Alex]
+
+We add the following warning suppression flags to all code generated by Alex:
+
+{-# OPTIONS_GHC -fno-warn-unused-matches #-}
+{-# OPTIONS_GHC -fno-warn-unused-binds #-}
+{-# OPTIONS_GHC -fno-warn-unused-imports #-}
+{-# OPTIONS_GHC -fno-warn-tabs #-}
+{-# OPTIONS_GHC -fno-warn-missing-signatures #-}
+
+Without these flags, current versions of Alex will generate code that is not
+warning free. Note that this is the result of Alex' internals, not of the way
+we have have written our (Lexer).x files.
+
+As always, we need code to be warning free when validating with -Werror.
+
+The list of flags is as short as possible (at the time of writing), to try to
+avoid suppressing warnings for bugs in our own code.
+
+TODO. Reevaluate this situation once Alex >3.1.4 is released. Hopefully you
+can remove these flags from all (Lexer).x files in the repository, and also
+delete this Note. Don't forget to update aclocal.m4, and send a HEADS UP
+message to ghc-devs.
+
+The first release of Alex after 3.1.4 will either suppress all warnings itself
+[1] (bad), or most warnings will be fixed and only a few select ones will be
+suppressed by default [2] (better).
+
+[1] https://github.com/simonmar/alex/commit/1eefcde22ba1bb9b51d523814415714e20f0761e
+[2] https://github.com/simonmar/alex/pull/69
+-}
 }