Using Haddock to document ADTs

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

On 10/22/07, Alfonso Acosta
========== Foolib.hs ============ -- | This is Foolib which is aimed at whatever module Foolib (ADT) where
import ADT
===================
Sorry, I meant (although my error was probably obvious) ========== Foolib.hs ============ -- | This is Foolib which is aimed at whatever module Foolib (ADT1) where import ADT1 ===================

Alfonso Acosta wrote:
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.
Haddock is designed to document APIs for the end-user rather than the developer, although it has been suggested several times that it could generate source-code documentation too. One way to do what you want is to split the module into two: module Lib.ADT.Internals (ADT(..)) where data ADT = C1 | ... | Cn module Lib.ADT (ADT) where import Lib.ADT.Internals developers can import the .Internals module, and end-users import the ADT module. Cheers, Simon

Simon Marlow wrote:
Alfonso Acosta wrote:
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.
Haddock is designed to document APIs for the end-user rather than the developer, although it has been suggested several times that it could generate source-code documentation too.
maybe first the paragraph for the end-user, followed by CURRENT IMPLEMENTATION DETAILS/NOTES: After all, those are sometimes relevant or interesting to the "end-user" (or are the implementation descriptions consistently several times longer than the API documentation, too distractingly?) Isaac

On 10/23/07, Isaac Dupree
maybe first the paragraph for the end-user, followed by CURRENT IMPLEMENTATION DETAILS/NOTES:
After all, those are sometimes relevant or interesting to the "end-user" (or are the implementation descriptions consistently several times longer than the API documentation, too distractingly?)
I personally think that giving implementation details to the _end-user_ is against the purpose of an ADT (even if you give details, due to the encapsulated nature of the ADT, the user cannot explicitly make use of them). What I was asking for is for a way to generate internal documentation for developers (who are entitled to know all the details). I would propose to use special annotations for developers. Then,a special flag could be provided (e.g. -fdev) to generate developer-docs. -fdev would also imply to generate the documentation based on the contents of each module instead of the export list (otherwise the developers wouldn't or example be able to get documentation for hidden constructors in the case of ADT's). I guess that's what Simon meant by "source-code documentation".
Isaac _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
participants (3)
-
Alfonso Acosta
-
Isaac Dupree
-
Simon Marlow