[Haskell-cafe] Haddock API and .haddock interface files questions

[Claus Reinke]

Some questions about Haddock usage:

1. Haddock executable and library are a single hackage package,
    but GHC seems to include only the former (haddock does not
    even appear as a hidden package anymore). Is that intended?

2. Naively, I'd expect Haddock processing to involve three stages:
    1. extract information for each file/package
    2. mix and match information batches for crosslinking
    3. generate output for each file/package

    I would then expect .haddock interface files to repesent the
    complete per-package information extracted in step 1, so 
    that packages with source can be used interchangeably
    with packages with .haddock files.

    However, I can't seem to use 'haddock --hoogle', say, with
    only .haddock interface files as input ("No input file(s).").

3. It would be nice if the Haddock executable was just a thin
    wrapper over the Haddock API, if only to test that the API
    exposes sufficient functionality for implementing everything
    Haddock can do.

    Instead, there is an awful lot of useful code in Haddock's
    Main.hs, which is not available via the API. So when coding
    against the API, for instance, to extract information from
    .haddock files, one has to copy much of that code.

    Also, some inportant functionality isn't exported (e.g., the
    standard form of constructing URLs), so it has to be copied
    and kept in synch with the in-Haddock version of the code.

    It might also be useful to think about the representation
    of the output of stage 2 above: currently, Haddock directly
    generates indices in XHtml form, even though much of
    the index computation should be shareable accross
    backends. That is, current "backends" seem to do both
    stage 2 and stage 3, with little reuse of code for stage 2.

It seems that exposing sufficient information in the API, and
allowing .haddock interface files as first-class inputs, there
should be less need for hardcoding external tools into Haddock
(such as --hoogle, or haddock-leksah). Instead, clients should
be able to code alternative backends separately, using Haddock
to extract information from sources into .haddock files, and
the API for processing those .haddock files. 

Are these expectations reasonable, or am I misreading the 
intent behind API and .haddock files? Is there any 
documentation about the role and usage of these two
Haddock features, as well as the plans for their development?

Claus