Haddock strings in .hi files
fuuzetsu at fuuzetsu.co.uk
Tue Mar 18 18:20:20 UTC 2014
I saw https://ghc.haskell.org/trac/ghc/ticket/5467 pop up in my inbox
and it reminded me of something I've been wondering for a while: why do
we not store Haddock docstrings in the interface file?
I think that if we did, we could do some great things:
1. Show docs in GHCi (I vaguely recall someone working on this ~1 year
ago, does anyone have any info?)
2. Allow Haddock to work a lot faster: the big majority of time spent
when creating documentation is actually spent by Haddock calling various
GHC functions, such as type-checking the modules. Only a small amount of
time is actually spent by Haddock on other tasks such as parsing or
outputting the documentation. If we could simply get everything we need
from the .hi files, we save ourselves a lot of time.
3. Allow Haddock to create partial documentation: a complaint I
sometimes hear is if anything at all in the project doesn't type check,
we don't get any documentation at all. I think that it'd be viable to
generate only the documentation for the modules/functions that do
type-check and perhaps skip type signatures for everything else.
Points 1. and 2. are of clear benefit. Point 3. is a simple afterthought
and thinking about it some more, I think that maybe it'd be possible to
do this with what we have right now: is type-checking separate parts of
the module supported? Can we retrieve documentation for the parts that
I am asking for input on what people think. I am not familiar at all
with what goes into the .hi file (and I can't find anything concrete! Am
I missing some wiki page?) at all and why. At the very least, 1. should
be easy to implement.
It was suggested that I submit a proposal for this as part of GSoC,
namely implementing 1. and 2.. I admit that having much faster
documentation builds would be amazing and Edward K. and Carter S. seem
to think that this is very do-able in the 3 month period that GSoC runs
While I say all this, I have already submitted my proposal on a
different topic. I am considering writing this up and submitting this as
well but I am looking for some insight into the problem first.
If there are any students around still looking for ideas, please do
speak up if you want to snatch this. If there are people that are eager
to mentor something like this then I suppose they should speak up too.
More information about the ghc-devs