aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlec Theriault <alec.theriault@gmail.com>2020-04-15 09:21:09 -0400
committerAlec Theriault <alec.theriault@gmail.com>2020-04-15 07:30:51 -0700
commit8d83110789def9207463a035fa766b78ebf5fdd9 (patch)
tree4caec3efdcc4b60995712a9337086571858633ff
parentd8aaaba9414b149fa7941d364b6d4a3fbcc1a520 (diff)
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.
-rw-r--r--haddock-api/src/Haddock/Interface/Create.hs17
1 files changed, 15 insertions, 2 deletions
diff --git a/haddock-api/src/Haddock/Interface/Create.hs b/haddock-api/src/Haddock/Interface/Create.hs
index af006d03..f29f576e 100644
--- a/haddock-api/src/Haddock/Interface/Create.hs
+++ b/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