Prune docstrings that are never rendered

When first creating a Haddock interface, trim `ifaceDocMap` and
`ifaceArgMap` to not include docstrings that can never appear in the
final output. Besides checking with GHC which names are exported, we
also need to keep all the docs attached to instance declarations (it is
much tougher to detect when an instance is fully private).

This change means:

  * slightly smaller interface files (7% reduction on boot libs)
  * slightly less work to do processing docstrings that aren't used
  * no warnings in Haddock's output about private docstrings (see #1070)

I've tested manually that this does not affect any of the boot library
generated docs (the only change in output was some small re-ordering in
a handful of instance lists). This should mean no docstrings have been
incorrectly dropped.

Author: harpocrates

haddock-api/src/Haddock/Interface/Create.hs

@@ -31,6 +31,7 @@ import Haddock.Interface.LexParseRn
 import Data.Bifunctor
 import Data.Bitraversable
 import qualified Data.Map as M
+import qualified Data.Set as S
 import Data.Map (Map)
 import Data.List (find, foldl', sortBy)
 import Data.Maybe
@@ -165,6 +166,18 @@ createInterface tm flags modMap instIfaceMap = do
 
   modWarn <- liftErrMsg (moduleWarning dflags gre warnings)
 
+  -- Prune the docstring 'Map's to keep only docstrings that are not private.
+  --
+  -- Besides all the names that GHC has told us this module exports, we also
+  -- keep the docs for locally defined class instances. This is more names than
+  -- we need, but figuring out which instances are fully private is tricky.
+  --
+  -- We do this pruning to avoid having to rename, emit warnings, and save
+  -- docstrings which will anyways never be rendered.
+  let !localVisibleNames = S.fromList (localInsts ++ exportedNames)
+      !prunedDocMap = M.restrictKeys docMap localVisibleNames
+      !prunedArgMap = M.restrictKeys argMap localVisibleNames
+
   return $! Interface {
     ifaceMod               = mdl
   , ifaceIsSig             = is_sig
@@ -173,8 +186,8 @@ createInterface tm flags modMap instIfaceMap = do
   , ifaceDoc               = Documentation mbDoc modWarn
   , ifaceRnDoc             = Documentation Nothing Nothing
   , ifaceOptions           = opts
-  , ifaceDocMap            = docMap
-  , ifaceArgMap            = argMap
+  , ifaceDocMap            = prunedDocMap
+  , ifaceArgMap            = prunedArgMap
   , ifaceRnDocMap          = M.empty
   , ifaceRnArgMap          = M.empty
   , ifaceExportItems       = prunedExportItems