tl;dr:

cabal is the culprit
If you have the `Extensions: CPP` directive in your .cabal file, then when invoking haddock, cabal causes every file to be pre-processed twice in sequence.
pre-processing isn't idempotent
when done under clang, it outputs things that ghc.

longer:

Regarding the ellusive problem whereby haddock for some packages fails on ghc-7.8.3 / haddock-2.14.2 systems with clang (as in OS X 10.9):

Bugs were filed for both haddock and cabal:

https://github.com/haskell/haddock/issues/284
https://github.com/haskell/cabal/issues/1740

I've been trying to find a work-around before releasing the platform for OS X. In sleuthing this I found the root cause: cabal.

Full details here: Root cause of haddock / clang failure

The correct fix is to change cabal's behavior: Either don't pre-process the fils for Haddock, or don't pass --optghc=-XCPP

There is no good work around: We could add -optP-P to all compilations, but that breaks line numbers for everything. We could wrap haddock to remove the --optghc=-XCPP, but that will break hand invocations of haddock.

- Mark