Add the OPAQUE pragma

A new pragma, `OPAQUE`, that ensures that every call of a named
function annotated with an `OPAQUE` pragma remains a call of that
named function, not some name-mangled variant.

Implements GHC proposal 0415:
https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0415-opaque-pragma.rst

This commit also updates the haddock submodule to handle the newly
introduced lexer tokens corresponding to the OPAQUE pragma.

2 files changed, 27 insertions, 0 deletions

diff --git a/docs/users_guide/9.4.1-notes.rst b/docs/users_guide/9.4.1-notes.rst
index caac4e9362..39ab943356 100644
--- a/docs/users_guide/9.4.1-notes.rst
+++ b/docs/users_guide/9.4.1-notes.rst
@@ -67,6 +67,9 @@ Compiler
 - The way GHC checks for representation polymorphism has been overhauled:
   all the checks are now done during typechecking. The error messages
   now contain more detailed information about the specific check that was performed.
+- A new pragma, :pragma:`OPAQUE`, that ensures that every call of a named function
+  annotated with an :pragma:`OPAQUE` pragma remains a call of that named function,
+  not some name-mangled variant.
 
 - The parsing of implicit parameters is slightly more permissive, as GHC now allows ::
 
diff --git a/docs/users_guide/exts/pragmas.rst b/docs/users_guide/exts/pragmas.rst
index f533dd834e..5aa4e9a783 100644
--- a/docs/users_guide/exts/pragmas.rst
+++ b/docs/users_guide/exts/pragmas.rst
@@ -454,6 +454,30 @@ arguments etc). Another way to understand the semantics is this:
 The same phase-numbering control is available for :pragma:`RULE <RULES>`\s
 (:ref:`rewrite-rules`).
 
+.. _opaque-pragma:
+
+``OPAQUE`` pragma
+-----------------
+
+.. pragma:: OPAQUE ⟨name⟩
+
+    :where: top-level
+
+    Instructs the compiler to ensure that every call of ``name`` remains a
+    call of ``name``, and not some name-mangled variant.
+
+The :pragma:`OPAQUE` pragma is an even stronger variant of the :pragma:`NOINLINE`
+pragma. Like the :pragma:`NOINLINE`, named functions annotated with a
+:pragma:`OPAQUE` pragma are not inlined, nor will they be be specialized.
+Unlike the :pragma:`NOINLINE`, named functions annotated with a
+:pragma:`OPAQUE` pragma are left untouched by the Worker/Wrapper transformation.
+Unlike :pragma:`NOINLINE`, :pragma:`OPAQUE` has no phase control.
+
+In effect, every call of a named function annotated with an :pragma:`OPAQUE`
+pragma remains a call of that named function, not some name-mangled variant.
+You shouldn't ever need to use the :pragma:`OPAQUE` pragma, unless you have a
+reason to care about name-mangling.
+
 .. _line-pragma:
 
 ``LINE`` pragma