[Haskell-cafe] Haddock and the qualified imports

[David Waern]

2011/12/6 Yves Parès <limestrael at gmail.com>:
> Hi,
>
> I noticed some time ago the fact that qualified imports doesn't affect the
> generated documentation.
> It's kind of clumsy in case of libraries that define a lot of synonyms
> (vector and bytestring come in my mind first).
> For instance, in the package utf8-string:
> http://hackage.haskell.org/packages/archive/utf8-string/0.3.7/doc/html/Data-ByteString-UTF8.html
>
> Here, the documentation doesn't say that the
> utf8-string/Data.ByteString.UTF8.ByteString datatype used all along comes in
> fact from Data.ByteString.
> If it were instead a new implementation of ByteString (as for
> bytestring/Data.ByteString.Char8.ByteString) the documentation would look
> exactly the same, so to disambiguate to reader has to crawl through the code
> to get to the initial definition.
> (clicking on a 'ByteString' doesn't even redirect you to the original
> bytestring/Data.ByteString page)
>
> It should be written that this 'ByteString' is not a newly defined type but
> instead a re-exportation.

It should be simple to add some kind of "Re-export of <link to
original thing>" tag to the Haddock documentation. Feel free to add a
ticket for this feature to the issue tracker
(trac.haskell.org/haddock) with a description of how it should work.

> It's even worse when you see the doc of a module that uses in the meantime
> lazy and strict ByteStrings, or normal and unboxed/storable/<insert flavour
> here> vector: you have to hover the type name to see which haddock page it
> points to.
>
> In that case, a solution might be to indicate on top of the doc page that it
> uses another module as a qualified import, and to keep the prefixes in the
> function signatures.

Maybe. But have you tried experimenting with Haddock's --qual flag?

David