[Haskell-cafe] improved jhc manual

[Mateusz Kowalczyk]

On 06/13/2014 07:33 AM, John Meacham wrote:
> On Wed, Jun 4, 2014 at 8:23 AM, Mateusz Kowalczyk
> <fuuzetsu at fuuzetsu.co.uk> wrote:
>> You're correct that there's no such feature at the moment. If you want
>> something, please open an issue on [1]. Note that I have never used JHC
>> or looked into how it works so I will need very careful description of
>> what I need to do to replicate it all, including small test case, any
>> flags that need to be passed in for Haddock to work with JHC, expected
>> behaviour, a small case where there are no recursive modules so I can
>> confirm it works in simple case &c. If it turns out to not be too
>> complicated then you could have it in the next non-minor release (2.15.x).
> 
> What would be easiest is to just bypass much of Haddocks middle end,
> as in, I don't want it to attempt to follow dependencies or figure out
> types or call ghc by itself at all. rather  I want to give it a
> pre-digested pap of resolved names and types (and whatever else it
> needs) but let haddock still parse the file and generate the
> documention with its back end. 

GHC does the parsing of stuff for us, as well as module loading, package
finding, name resolution, renaming, …. What we do parse is the things
that GHC tells us are Haddock comments (the stuff you actually write).

What you'd need to produce for us to use XHtml backend is [Interface]
where Interface is defined in Haddock.Types. Notably, this involves
LHsDecl which is a GHC type which the back-end inspects and decides what
to do with.

What's more, we use some pretty printing functions from GHC to actually
render the stuff. Basically, GHC does the bulk of work and we massage
whatever we get back into a friendlier format for humans to read.

If you don't want to involve GHC at all then it's not feasible to use
Haddock. There *are* plans to splice out the parts that don't need GHC
to a separate package (currently unimaginatively called haddock-library)
and I have already done so with the comment parser (so you can turn
String into Haddock doc type) but there are no plans to just not use GHC
all together, it is too much work. We are planning to make writing new
back-ends easier but the GHC dependency will not go away.

So the short version is, there is no GHC middle-end, it is GHC from the
beginning to the end.

One way to work around this would be to pre-process what we get out of
GHC into Haddock types that no longer refer to the GHC data types that
we can expose and back-ends can work with but this is rather a lot of
work. It seems like a correct thing to do but I don't think the amount
of effort justifies it, at least for me. We just don't have the manpower
for this: we're *very* understaffed for such a core project. If you know
people who would like to work towards such goal though, I'd love to hear
about it.

> This would be more generally useful as
> a haddock feature than trying to have it emulate  other compilers as
> any compiler or tool can output this general metainfo format.
> 
>    John
> 


-- 
Mateusz K.