The lexer parses a HsDoc RdrName from each docstring. This is a raw
docstring combined with a list of identifiers found in the docstring
and the RdrNames created from each identifier.
The renamer then turns each HsDoc RdrName into a HsDoc Name,
replacing each RdrName with a list of Names.
When including docstrings in ModGuts or ModIface, we split a
HsDocNamesMap off the collected docs. This map collects all lexed
identifiers and the Names they may correspond to.
https://github.com/haskell/haddock/pull/828 demonstrates how haddock
may use the new .hi-file output.
We compare this patch with a version of GHC before the changes but
which includes the ByteString docstring patch from D4743.
The modules we compile are
a medium-sized and well documented module, and Options.GenericNoDocs,
a version of Options.Generic with all docstrings removed.
Before (inludes ByteString docstring patch) Now Module: Options.Generic -haddock: off Compile time: 810.0 ms 816.3 ms max_bytes_used: 52,170,808 52,805,264 peak_megabytes_allocated: 172 174 Size of hi-file in bytes: 33,864 33,792 -haddock: on Compile time: 807.1 ms 820.2 ms max_bytes_used: 51,838,320 52,957,272 peak_megabytes_allocated: 170 175 Size of hi-file in bytes: 33,864 50,081 Module: Options.GenericNoDocs -haddock: off Compile time: 813.9 ms 818.5 ms max_bytes_used: 51,845,232 52,789,944 peak_megabytes_allocated: 171 174 Size of hi-file in bytes 33,864 33,792 -haddock: on Compile time: 809.7 ms 817.3 ms max_bytes_used: 51,844,840 52,801,504 peak_megabytes_allocated: 171 174 Size of hi-file in bytes: 33,864 33,792
Add a :doc command to GHCi that shows the documentation for an identifier.
Ideas for further work
- Remove the dependency on parsec.
- Add an option to configure the identifier delimiters the lexer looks for.
- Add an option to make the lexer exclude birdtracks.