Haddock strings in .hi files
fuuzetsu at fuuzetsu.co.uk
Wed Mar 19 12:30:06 UTC 2014
On 19/03/14 11:39, Simon Marlow wrote:
> On 18/03/2014 18:20, Mateusz Kowalczyk wrote:
>> Hi all,
>> 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.
> Don't you still have to run the renamer at least? And in GHC, renaming
> is tied up with typechecking, so it's hard to do one without the other.
> Furthermore, if there is a missing type signature it's useful to be
> able to put the inferred type in the documentation. I think I'm missing
> the point somewhere - how does putting docs in the .hi file let you
> avoid typechecking?
This is a very good point and precisely why I have e-mailed ghc-devs
first. I think you're correct. I suppose that idea is out of the window!
> I'm not really sure I see the benefit. If Haddock provided a library
> that we can call from GHCi to get documentation, then we could show
> documentation in GHCi.
Considering that (as you point out), we can't really get rid of the time
spent in GHC on renaming/type-checking, this does seem like the best way
to go now. I think there's an old ticket somewhere about providing such
a library that would let you work with Haddock interface files. I'll
investigate that approach in some spare time.
> The current design is intended to separate Haddock from GHC as much as
> possible, but putting documentation in .hi files would be going in the
> opposite direction. There would have to be a compelling reason to do
> that, something that we couldn't do another way.
I agree. Without being able to rip the major benefit of the idea (fast
docs), it is not worth doing it now.
More information about the ghc-devs