Add a -no-haddock flag.

This flag undoes the effect of a previous "-haddock" flag.  Having both flags makes it easier
for build systems to enable Haddock parsing in a set of global flags, but then disable it locally for
specific targets (e.g., third-party packages whose comments don't pass the validation in the latest GHC).

I added the flag to expected-undocumented-flags.txt since `-haddock` was alreadyin that list.

5 files changed, 26 insertions, 1 deletions

diff --git a/compiler/GHC/Driver/Session.hs b/compiler/GHC/Driver/Session.hs
index ac0bbbd286..b0db896439 100644
--- a/compiler/GHC/Driver/Session.hs
+++ b/compiler/GHC/Driver/Session.hs
@@ -2571,6 +2571,7 @@ dynamic_flags_deps = [
   , make_ord_flag defGhcFlag "ghcversion-file"      (hasArg addGhcVersionFile)
   , make_ord_flag defGhcFlag "main-is"              (SepArg setMainIs)
   , make_ord_flag defGhcFlag "haddock"              (NoArg (setGeneralFlag Opt_Haddock))
+  , make_ord_flag defGhcFlag "no-haddock"           (NoArg (unSetGeneralFlag Opt_Haddock))
   , make_ord_flag defGhcFlag "haddock-opts"         (hasArg addHaddockOpts)
   , make_ord_flag defGhcFlag "hpcdir"               (SepArg setOptHpcDir)
   , make_ord_flag defGhciFlag "ghci-script"         (hasArg addGhciScript)
diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index 837c2a59e2..ea8543b58c 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -127,7 +127,6 @@
 -fuse-rpaths
 -fversion-macros
 -fvia-c
--haddock
 -haddock-opts
 -hpcdir
 -instantiated-with
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 86094cc9cc..7bdd421fac 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -1129,6 +1129,26 @@ Some flags only make sense for particular target platforms.
     :ref:`native code generator <native-code-gen>`. The resulting compiled
     code will only run on processors that support BMI2 (Intel Haswell and newer, AMD Excavator, Zen and newer).
 
+Haddock
+-------
+
+.. index::
+   single: haddock
+
+.. ghc-flag:: -haddock
+    :shortdesc: Make the parser more strict about Haddock comments.
+    :type: dynamic
+    :reverse: -no-haddock
+    :category: misc
+
+    By default, GHC ignores Haddock comments (``-- | ...`` and ``-- ^ ...``)
+    and does not check that they're associated with a valid term, such as a
+    top-level type-signature.  With this flag GHC will parse Haddock comments
+    and include them in the interface file it produces.
+
+    Note that this flag makes GHC's parser more strict so programs which are
+    accepted without Haddock may be rejected with :ghc-flag:`-haddock`.
+
 Miscellaneous flags
 -------------------
 
diff --git a/testsuite/tests/haddock/should_compile_noflag_nohaddock/all.T b/testsuite/tests/haddock/should_compile_noflag_nohaddock/all.T
index 1c68255e1b..c6e47b729b 100644
--- a/testsuite/tests/haddock/should_compile_noflag_nohaddock/all.T
+++ b/testsuite/tests/haddock/should_compile_noflag_nohaddock/all.T
@@ -11,3 +11,4 @@ test('haddockD001', normal, compile, [''])
 test('haddockD002', normal, compile, [''])
 test('haddockD003', normal, compile, [''])
 test('haddockD004', normal, compile, [''])
+test('haddockD005', normal, compile, ['-haddock -no-haddock'])
diff --git a/testsuite/tests/haddock/should_compile_noflag_nohaddock/haddockD005.hs b/testsuite/tests/haddock/should_compile_noflag_nohaddock/haddockD005.hs
new file mode 100644
index 0000000000..b4c6c69abd
--- /dev/null
+++ b/testsuite/tests/haddock/should_compile_noflag_nohaddock/haddockD005.hs
@@ -0,0 +1,4 @@
+module F where
+
+type F = (Int -- | x
+            )