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