Haddock strings in .hi files

[Simon Peyton Jones]

| 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.

Actually it would in many ways be easier to put Haddock stuff in .hi files.  But since GHC writes the .hi file, that would essentially mean merging GHC and Haddock into a single compile-and-documentation-generator.   That would be cool in a way -- for example, GHCi would natively have access to the Haddock docs for a function.

As Simon M says, the big reason not to do that is because it couples together two large projects, making each harder to develop independently.  And that's a pretty big reason.

Simon

| -----Original Message-----
| From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of Simon
| Marlow
| Sent: 19 March 2014 11:40
| To: Mateusz Kowalczyk; ghc-devs at haskell.org
| Subject: Re: Haddock strings in .hi files
| 
| 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?
| 
| 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.
| 
| 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.
| 
| Cheers,
| Simon
| 
| 
| > 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 don't type-check?
| >
| > 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 over.
| >
| > 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.
| >
| > Thanks!
| >
| _______________________________________________
| ghc-devs mailing list
| ghc-devs at haskell.org
| http://www.haskell.org/mailman/listinfo/ghc-devs