Serialize docstrings to ifaces, display them with new GHCi :doc command

If `-haddock` is set, we now extract docstrings from the renamed ast
and serialize them in the .hi-files.

This includes some of the changes from D4749 with the notable
exceptions of the docstring lexing and renaming.

A currently limited and experimental GHCi :doc command can be used
to display docstrings for declarations.

The formatting of pretty-printed docstrings is changed slightly,
causing some changes in testsuite/tests/haddock.

Test Plan: ./validate

Reviewers: alexbiehl, hvr, gershomb, harpocrates, bgamari

Reviewed By: alexbiehl

Subscribers: rwbarton, thomie, carter

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

5 files changed, 93 insertions, 0 deletions

diff --git a/testsuite/tests/showIface/DocsInHiFile.hs b/testsuite/tests/showIface/DocsInHiFile.hs
new file mode 100644
index 0000000000..26156722ac
--- /dev/null
+++ b/testsuite/tests/showIface/DocsInHiFile.hs
@@ -0,0 +1,37 @@
+{-| `elem`, 'print',
+`Unknown',
+'<>', ':=:', 'Bool'
+-}
+module DocsInHiFile
+  ( DocsInHiFile.elem
+  , D(..)
+  , add
+  , P(..)
+  , Show(..)
+  ) where
+
+-- | '()', 'elem'.
+elem :: ()
+elem = ()
+
+-- | A datatype.
+data D
+  = D0 -- ^ A constructor for 'D'. '
+  | D1 -- ^ Another constructor
+  deriving ( Show -- ^ 'Show' instance
+           )
+
+add :: Int -- ^ First summand for 'add'
+    -> Int -- ^ Second summand
+    -> Int -- ^ Sum
+add a b = a + b
+
+-- | A class
+class P f where
+  -- | A class method
+  p :: a -- ^ An argument
+    -> f a
+
+-- | Another datatype...
+data D'
+-- ^ ...with two docstrings.
diff --git a/testsuite/tests/showIface/DocsInHiFile0.stdout b/testsuite/tests/showIface/DocsInHiFile0.stdout
new file mode 100644
index 0000000000..e1c32d63c8
--- /dev/null
+++ b/testsuite/tests/showIface/DocsInHiFile0.stdout
@@ -0,0 +1,4 @@
+module header:
+  Nothing
+declaration docs:
+arg docs:
diff --git a/testsuite/tests/showIface/DocsInHiFile1.stdout b/testsuite/tests/showIface/DocsInHiFile1.stdout
new file mode 100644
index 0000000000..fcb5f94f71
--- /dev/null
+++ b/testsuite/tests/showIface/DocsInHiFile1.stdout
@@ -0,0 +1,36 @@
+module header:
+  Just " `elem`, 'print',
+`Unknown',
+'<>', ':=:', 'Bool'
+"
+declaration docs:
+  D':
+    " Another datatype...
+
+ ...with two docstrings."
+  P:
+    " A class"
+  p:
+    " A class method"
+  D:
+    " A datatype."
+  D0:
+    " A constructor for 'D'. '"
+  D1:
+    " Another constructor"
+  elem:
+    " '()', 'elem'."
+  $fShowD:
+    " 'Show' instance"
+arg docs:
+  p:
+    0:
+      " An argument"
+  add:
+    0:
+      " First summand for 'add'"
+    1:
+      " Second summand"
+    2:
+      " Sum"
+
diff --git a/testsuite/tests/showIface/Makefile b/testsuite/tests/showIface/Makefile
index 49b90342b3..7eafdfc9d2 100644
--- a/testsuite/tests/showIface/Makefile
+++ b/testsuite/tests/showIface/Makefile
@@ -5,3 +5,11 @@ include $(TOP)/mk/test.mk
 Orphans:
 	'$(TEST_HC)' $(TEST_HC_OPTS) -c Orphans.hs
 	'$(TEST_HC)' $(TEST_HC_OPTS) --show-iface Orphans.hi | grep -E '^(instance |family instance |"myrule)' | grep -v 'family instance modules:'
+
+DocsInHiFile0:
+	'$(TEST_HC)' $(TEST_HC_OPTS) -c DocsInHiFile.hs
+	'$(TEST_HC)' $(TEST_HC_OPTS) --show-iface DocsInHiFile.hi | grep -A 4 'module header:'
+
+DocsInHiFile1:
+	'$(TEST_HC)' $(TEST_HC_OPTS) -c -haddock DocsInHiFile.hs
+	'$(TEST_HC)' $(TEST_HC_OPTS) --show-iface DocsInHiFile.hi | grep -A 100 'module header:'
diff --git a/testsuite/tests/showIface/all.T b/testsuite/tests/showIface/all.T
index 5c89b70b59..df5d5cd9ec 100644
--- a/testsuite/tests/showIface/all.T
+++ b/testsuite/tests/showIface/all.T
@@ -1 +1,9 @@
 test('Orphans', normal, run_command, ['$MAKE -s --no-print-directory Orphans'])
+test('DocsInHiFile0',
+     extra_files(['DocsInHiFile.hs']),
+     run_command,
+     ['$MAKE -s --no-print-directory DocsInHiFile0'])
+test('DocsInHiFile1',
+     extra_files(['DocsInHiFile.hs']),
+     run_command,
+     ['$MAKE -s --no-print-directory DocsInHiFile1'])