GHC.Prim docs: note and test

6 files changed, 22 insertions, 6 deletions

diff --git a/compiler/GHC/Builtin/PrimOps.hs b/compiler/GHC/Builtin/PrimOps.hs
index 75622f7399..b6d7f898ef 100644
--- a/compiler/GHC/Builtin/PrimOps.hs
+++ b/compiler/GHC/Builtin/PrimOps.hs
@@ -168,11 +168,7 @@ primOpFixity :: PrimOp -> Maybe Fixity
 *                                                                      *
 ************************************************************************
 
-@primOpDocs@ contains the documentation from @primops.txt@ as a list of
-pairs (name, docs). We use stringy names here because wired-in names are
-not available yet, and not all of them are a @PrimOp@ (they could be
-tycons or pseudoops for example)
-
+See Note [GHC.Prim Docs]
 -}
 
 primOpDocs :: [(String, String)]
diff --git a/compiler/GHC/Iface/Load.hs b/compiler/GHC/Iface/Load.hs
index 4a0ed966d1..5fca78c67c 100644
--- a/compiler/GHC/Iface/Load.hs
+++ b/compiler/GHC/Iface/Load.hs
@@ -1050,7 +1050,7 @@ ghcPrimIface
         mi_decls    = [],
         mi_fixities = fixities,
         mi_final_exts = (mi_final_exts empty_iface){ mi_fix_fn = mkIfaceFixCache fixities },
-        mi_decl_docs = ghcPrimDeclDocs
+        mi_decl_docs = ghcPrimDeclDocs -- See Note [GHC.Prim Docs]
         }
   where
     empty_iface = emptyFullModIface gHC_PRIM
diff --git a/testsuite/tests/ghci/scripts/all.T b/testsuite/tests/ghci/scripts/all.T
index 7bb6043b8b..fd0ac2ce3a 100755
--- a/testsuite/tests/ghci/scripts/all.T
+++ b/testsuite/tests/ghci/scripts/all.T
@@ -105,6 +105,7 @@ test('ghci062', [extra_files(['ghci062/', 'ghci062/Test.hs']),
 test('ghci063', normal, ghci_script, ['ghci063.script'])
 test('ghci064', normal, ghci_script, ['ghci064.script'])
 test('ghci065', [extra_hc_opts("-haddock")], ghci_script, ['ghci065.script'])
+test('ghci066', normal, ghci_script, ['ghci066.script'])
 test('T2452', [extra_hc_opts("-fno-implicit-import-qualified")],
     ghci_script, ['T2452.script'])
 test('T2766', normal, ghci_script, ['T2766.script'])
diff --git a/testsuite/tests/ghci/scripts/ghci066.script b/testsuite/tests/ghci/scripts/ghci066.script
new file mode 100644
index 0000000000..7fb4be7520
--- /dev/null
+++ b/testsuite/tests/ghci/scripts/ghci066.script
@@ -0,0 +1,2 @@
+:set -XMagicHash
+:doc GHC.Prim.byteSwap#
diff --git a/testsuite/tests/ghci/scripts/ghci066.stdout b/testsuite/tests/ghci/scripts/ghci066.stdout
new file mode 100644
index 0000000000..ab85afa1a6
--- /dev/null
+++ b/testsuite/tests/ghci/scripts/ghci066.stdout
@@ -0,0 +1 @@
+Swap bytes in a word.
diff --git a/utils/genprimopcode/Main.hs b/utils/genprimopcode/Main.hs
index 63b51b9f5d..576dbc9a20 100644
--- a/utils/genprimopcode/Main.hs
+++ b/utils/genprimopcode/Main.hs
@@ -789,6 +789,22 @@ gen_switch_from_attribs attrib_name fn_name (Info defaults entries)
                -> unlines alternatives
                   ++ fn_name ++ " _ = " ++ getAltRhs xx ++ "\n"
 
+{-
+Note [GHC.Prim Docs]
+~~~~~~~~~~~~~~~~~~~~
+For haddocks of GHC.Prim we generate a dummy haskell file (gen_hs_source) that
+contains the type signatures and the commends (but no implementations)
+specifically for consumption by haddock.
+
+GHCi's :doc command reads directly from ModIface's though, and GHC.Prim has a
+wired-in iface that has nothing to do with the above haskell file. The code
+below converts primops.txt into an intermediate form that would later be turned
+into a proper DeclDocMap.
+
+We output the docs as a list of pairs (name, docs). We use stringy names here
+because mapping names to "Name"s is difficult for things like primtypes and
+pseudoops.
+-}
 gen_wired_in_docs :: Info -> String
 gen_wired_in_docs (Info _ entries)
   = "primOpDocs =\n  [ " ++ intercalate "\n  , " (catMaybes $ map mkDoc $ concatMap desugarVectorSpec entries) ++ "\n  ]\n"