This extends my work from D4758 and enables haddock to generate docs
from information enclosed in the .hi interface files.
- HaddockLex contains an Alex-based lexer for docstrings that detects identifiers delimited with ' or backticks.
- HsDoc.Docs comprises the DeclDocMap and ArcDocMap structures added in D4758 and other data needed by haddock.
- haddock now uses GhcMake.load' to load .hi-files, hooking into GHC's recompilation avoidance. In order to avoid recompilation when a .hi-file already contains documentation we use a new option Opt_SkipIfaceVersionCheck.
TODOs and requests for comment
- Work out a specification for a deterministic module structure (docs_structure) and update the existing code to implement it. The HaddockIssue849 test case is currently flaky because the ordering of constructors in the Avail for Maybe fluctuates.
- Possibly fuse mi_exports and docs_structure. Currently both serialize the same Avails.
- Get the recompilation avoidance right: While some of the checks performed in checkVersions are irrelevant for haddock, we may want to keep some of them. We probably also want -haddock to cause recompilation if an existing .hi-file doesn't contain the Docs.
- Fix the tests. ./validate currently reports failures for TEST="HaddockIssue849 ImpSafeOnly01 ImpSafeOnly02 ImpSafeOnly03 ImpSafeOnly04 ImpSafeOnly05 ImpSafeOnly06 ImpSafeOnly07 ImpSafeOnly08 ImpSafeOnly09 ImpSafeOnly10 Splices T13168 T14304 T4029 T9881 break006 break011 break013 break024 cabal01 dynamicToo002 dynamicToo005 haddock.base haddock.compiler hist001 hist002 plugins09 plugins11 print026 safePkg01"
Several more (minor) issues are marked TODO in the source code.
The corresponding changes in haddock are here.
Possible further work
- Add an option to configure the identifier delimiters the lexer looks for.
- Add an option to make the lexer exclude birdtracks.
- Make the :doc command also pretty-print arg docs.