[commit: ghc] master: Add Note [Warnings in code generated by Alex] (db530f1)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/db530f18784fe1a29394470a0edc56702727bcde/ghc

>---------------------------------------------------------------

commit db530f18784fe1a29394470a0edc56702727bcde
Author: Thomas Miedema <thomasmiedema at gmail.com>
Date:   Mon Jul 6 20:28:04 2015 +0200

    Add Note [Warnings in code generated by Alex]
    
    Differential Revision: https://phabricator.haskell.org/D1044


>---------------------------------------------------------------

db530f18784fe1a29394470a0edc56702727bcde
 compiler/cmm/CmmLex.x       |  6 +-----
 compiler/parser/Lexer.x     | 42 +++++++++++++++++++++++++++++++++++-------
 utils/genprimopcode/Lexer.x |  6 +-----
 3 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/compiler/cmm/CmmLex.x b/compiler/cmm/CmmLex.x
index fca5a1e..89ae796 100644
--- a/compiler/cmm/CmmLex.x
+++ b/compiler/cmm/CmmLex.x
@@ -11,16 +11,12 @@
 -----------------------------------------------------------------------------
 
 {
+-- 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 #-}
--- 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
 
 module CmmLex (
    CmmToken(..), cmmlex,
diff --git a/compiler/parser/Lexer.x b/compiler/parser/Lexer.x
index 98d167d..01e7de3 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
+-}
 }
diff --git a/utils/genprimopcode/Lexer.x b/utils/genprimopcode/Lexer.x
index 3ec6c2e..ad2590b 100644
--- a/utils/genprimopcode/Lexer.x
+++ b/utils/genprimopcode/Lexer.x
@@ -1,15 +1,11 @@
 
 {
+-- 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-tabs #-}
 {-# OPTIONS_GHC -fno-warn-missing-signatures #-}
 {-# OPTIONS_GHC -fno-warn-unused-imports #-}
--- 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
 
 module Lexer (lex_tok) where