Quoting Jérémy Bobbio (jeremy.bobbio@etu.upmc.fr):
I really see Literate Haskell and Haddock as two orthogonal tools, and that help me to focus when writing docs.
It impresses me SO much that the COMPUTER SCIENTIST have found a WAY to ELEVATE mere tools likke Haddock and Literate Haskell as elements in a VECTOR SPACE. Furthermore it seems that the SAME vector space has LANGUAGES as well, and moreso; It is an INNER PRODUCT SPACE, since one can talk about ORTHOGONALITY. One could have used the term ''Lineraly independent set'', but NO! One should use the magical, term Orthogonal! Heed my words! Orthogonal! Fun aside, I think you are right, but I disagree literate haskell is the way to write the ``how does this fit together'' question. Having just completed a quite big program written all in literate style, I can actually put up some comments about it: * It is hard. There is a thin line between having meaningful information in the comments and nothing but redundancy, compared to the source code. * There is many changes. All the time you change code semantics and then you have to read the comments around and check them for correctness. * There is an abstraction gap. Your thoughts can separately be given at a very high level. If interspersed with code, you are explaining at a much lower (and precise) level what your program is actually doing. I have a program of 2500 Lines. It is, typeset in LaTeX, 155 pages of report and literate documentation. That is awfully much for 2500 Lines of source code. Currently my feeling is that the added effort of writing it literate style does not add to the general understanding of the source code. This is partly because the source code is imperative at many points (it is ML - who said you can't just push in a couple of ref cells?). And also because the code in question is quite complex (due to the destructive updates, actually). I think you want 3 things: * API documentation (Haddock fills this gap). It is the for the programmer who wants to see how a given function should be called and be given the abstract view of it's semantics as a black box. Furthermore, Haddock provides a very succintly different but important view of my Modules: The ``SML signature'' view to type annotations, where type annotations are all presented in the same location for overview and is disconnected from the actual implementation. Together with proper documentation, this gives a very good overview over programs. * Documentation of the ``hard semantical parts''. The meaning of some functions needs elaboration since they are either hard to understand or they have some subtle point you commonly overlook. * Documentation of the high-level structure. My view is that Haddock, code comments and LaTeX fits these 3 quite well. On the other hand, if writing code by example to teach others about it, sending email with code etc, I like to have literate haskell style. But I do not tend to use it for large projects. -- jlouis