Skip to content

Haddock interfaces produced from `.hi` files

Hécate Moonlight requested to merge wip/hi-haddock-3 into ghc-head

= Summary

This is a large architectural change to how Haddock interfaces are computed. This is a rebased variant of the second half of Simon Jakobi's (@sjakobi) Hi Haddock GSOC project.

The idea is to work over top of the contents of .hi files instead of over the internal compiler representations of ASTs. This has a wide array of benefits, but two main ones are:

  • Haddock doesn't necessarily need to recompile modules to generate docs - if the right .hi files already exist, it'll automatically load them. Even better: this is nothing more that the existing recompilation avoidance logic in GHC.

  • Haddock no longer operates over concrete syntax - all declarations in the final docs are the result of reifying a TyThing. This means that the docs can be somewhat agnostic of users' particular choice to add certain kind annotations, use certain special syntax, etc.

== Before

Very roughly the previous way this worked was:

  1. A plugin is installed that saves GHCs renamed and typechecked sources

  2. GhcMake.load' is used to load .hi-files into GHC

  3. The parsed and renamed sources in the typechecked module are traversed in various ways accumulating all the right info

== After

Now, the process

  1. GhcMake.load' is used to load .hi-files into GHC

  2. The loaded interfaces are traversed in dependency order to get the information required to generate documentation

(cherry picked from commit 41ed9c36) (cherry picked from commit 9cc652cc2d989617c02dc3db14b7c2b768276baf)

Don't write iface

Perf and updates

Merge request reports