Broken documentation on Hackage.

[Johan Tibell]

On Mon, Jan 6, 2014 at 3:33 PM, Brandon Allbery <allbery.b at gmail.com> wrote:

> On Mon, Jan 6, 2014 at 5:27 AM, Malcolm Wallace <malcolm.wallace at me.com>wrote:
>>
>> I think the fundamental problem is that Haddock is now built on top of
>> ghc.  So if a package cannot be built by ghc (for whatever reason, e.g.
>> missing C library dependency), then it cannot be documented either.  This
>> is a good deal less than useful.  A documentation generator ought to do a
>> reasonable job, even if the code it is looking at is technically
>> not-compilable.
>>
>> At work, we have a stand-alone documentation generator for Haskell, which
>> requires no compiler.  Haddock also was once stand-alone.  I think it might
>> be time to wind the clock backwards and retrieve this desirable property.
>>
>
> The problem with that was you didn't get documentation if you used any GHC
> extension added within the past year or so. You can't win....
>

This problem keeps popping up in our various tooling efforts so I thought
it'd be worth pointing out that the general problem has been discussed in a
paper.

Martin Odersky touched on the more general problem of trying to have two

 * complete (e.g. supporting all extensions in our case) and
 * identically behaving

implementations of the same compiler (or part of a compiler in our case) in
the Scalable Component Abstractions paper [1]. It is very difficult and
requires a huge amount of work. The Scala solution is the cake pattern
which lets the Scala compiler expose itself as two different APIs, used for
two different purposes (in their case the compiler proper and a reflection
API).

Even if relying on the GHC API is a bit of a pain, it's better than relying
on a subtly different implementation that supports some subset of the
features.

1. http://lampwww.epfl.ch/~odersky/papers/ScalableComponent.pdf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/cabal-devel/attachments/20140106/e0fefa01/attachment.html>