Haddock strings in .hi files

[Mateusz Kowalczyk]

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.

> Cheers,
> Simon
> 
> 

Thanks!

-- 
Mateusz K.