Skip to content

WIP: Haddock: generate docs from .hi files

Alec Theriault requested to merge harpocrates/ghc:wip/hi-haddock into master

This adds to .hi interface files all the remaining information Haddock needs to generate doc pages. The work was started in 85309a3c (where only docstrings where extracted and serialized in .hi files). This is a rebased variant of the second half of Simon Jakobi's (@sjakobi) Hi Haddock GSOC project.

  • docstrings are bundled together with information about the identifiers they contain (see the new HsDoc name type which replaces HsDocString in many places).

  • all doc-related information is now located on the mi_docs field of ModIface. This aggregates arg docs, decl docs, module header docs, as well as some less obvious things Haddock needs (Haddock options, name chunks, extensions enabled, module structure)

As before, this information is only added to .hi files in the presence of -haddock. The utils/haddock submodule bump is a significant change for Haddock:

  • Haddock now uses GhcMake.load' to load .hi-files, hooking into GHC's recompilation (and avoiding parseModule/typecheckModule). Not only is this more robust, but it means that modules need only be recompiled if interface files with docstrings don't already exist.

  • Haddock no longer needs to inspect TypecheckedModule - ModIface is now enough! \o/

See #15786 (closed)

Original phabricator differential: https://phabricator.haskell.org/D5067

Merge request reports