[Haskell-cafe] Re: Using Haddock to document ADTs

[Alfonso Acosta]

On 10/23/07, Isaac Dupree <isaacdupree at charter.net> wrote:
> 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 at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>