Haddock strings in .hi files
fuuzetsu at fuuzetsu.co.uk
Thu Mar 20 10:39:47 UTC 2014
On 20/03/14 08:08, Simon Peyton Jones wrote:
> | 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.
Wasn't this the case years ago? I was under the impression (from commit
messages and various bits in source comments and on the web) that
Haddock used to sit directly in GHC and then got ripped out by Simon M
and David W. Putting it back into GHC seems like a step back, especially
because as Simon M mentions, the functionality to grab documentation for
something can be provided by Haddock and GHCi then can use that. I think
an extra benefit of this is that we get to decide in Haddock how we
present such documentation: we can have different pretty printers if we
so desire. If the strings are in .hi files themselves, the only choice
is to show them verbatim which can be sub-par.
So if having documentation in GHCi is the sole goal, I think it's not
worth putting the strings in the .hi file. If it were to speed up
Haddock dramatically then I would be much less reluctant but as Simon M
points out, that idea doesn't really work. I think if we are to speed up
Haddock, something clever does need to happen in GHC and Haddock but now
I don't think that putting the strings in .hi files is the way to
achieve that. I also can see quite a few people upset about further
coupling of Haddock and GHC and bloating up the .hi files with extra data.
What do you think?
More information about the ghc-devs