[Haskell-cafe] Using Haddock to document ADTs

[Alfonso Acosta]

Hi all,

I'm beginning to get familiar with Haddock and I want to document a
library which, as usually happens, has some ADT definitions.

I'd like to document the ADTs both for the end-user (who shouldn't be
told about its internal implementation) and future developers.


Let's imagine my library is called FooLib, defines an ADT whose
implementation is hidden by an outer module.

=========== FooLib/ADT1.hs =====
-- | This module defines my type ADT1
module ADT1

-- | This type implements whatever and. As you can see it's implemented
--  using blah blah so that is more efficient because of  blah blah
data ADT1 a = ...

========== Foolib.hs ============
-- | This is Foolib which is aimed at whatever
module Foolib (ADT) where

import ADT

===================

Generating documentation for Foolib.hs with this Haddock annotations
will unfortunatelly reveal implementation details since the annotation
of ADT1 is forwarded.

My question is, How can I generate documentation for both developers
and the end-users using the same Haddock annotations?

I'm beginning to think it would be a good idea to distinguish those
two cases (documentation for end-users and internal developers) in
Haddock, but I'm probably wrong since it seems a common thing and
wasn't implemented yet.

Best Regards,

Alfonso