I produced two samples of "long interface", extracted by module Extractor and formatted by my new module InterfacePrinter. Both samples interface to the latter. One is an unformatted ascii version (yyy.txt) and the other (yyy.html) is html formatted. The latter is intentionally link-free, but the cross references can be produced with ease if needed, since Extractor produces well structured data representing the module. Both samples can be found in http://www.numeric-quest.com/haskell/. I edited the html version a bit, adding few items for completness (exports, imports, classes, instances). The reason for this is that those edited items are temporarily treated as strings, and not structured as yet by Extractor. But the rest has been automatically generated and -- aside from the edited part -- both versions are factually identical. I wish to make the following points: 1. No heavy formatting information is stored in the source file from which the interface has been extracted. However, there are three hints for html beautifier from InterfacePrinter module. a. Those words in function comments which are intentionally embedded in single quotes, refer to function arguments. The printer uses this hint to produce italic emphases for html version. This hint is also used to prettyfy module comment (top of the page) as well, in order to emphasize certain keywords. b. Similarly, double quotes could be used as hints to produce bold emphases. However, I do not use it so far. c. The last hint signifies headers of groups of functions, which I call "categories". The hint is a comment that starts with "--: ". All other delimiters are stripped off. As an example, the banner: --------------------------------- --: interface listings - exported --------------------------------- will be replaced by a single line of this category header: "category: interface listing - exported". This line will be printed in bold when using html format. In summary, the formatting information embedded in the sources is very lightweight and does not compromise readability of sources. I would even argue that this helps to write well structured comments. The cycle: write and document a module, extract its interface, try to decide whether such interface is able to stand on its own and represents readable piece, go back and edit your comments again ... should certainly produce well structured and readable documentation. 2. Ascii version has its own merits too. For example, by typing in Hugs Prelude> f "someFunction" "someSource" shortList Ascii you should see the interface of function "someFunction" extracted from "someSource". This includes the function signature and comments. Similarly, you can browse the full listing of this function by specifying: codeList instead of shortList. Isn't that neat? But this is just a side effect. Function 'f' has been designed for random testing of module Extractor. Variety of interface types can be produced, once both modules are ready. I list them in the footnotes of yyy.txt or yyy.html. So far, the "long interface" (all entities, including private ones) is roughly defined. Regards, Jan