On Tue, 30 Jan 2001, Simon Marlow wrote:
- a big win is that even without any annotations, you get documentation for free (i.e. hyperlinked type signatures for exported functions, class definitions, etc.). Just having this working would make we very happy :)
Right, but without the comments. The question of compiler support aside ...
And there's an upgrade path: if we define the "interface-file" format to be exactly the same as the syntax of a Haskell module (perhaps with code optinoal), then the compiler can always just read a source file and output the same file with types filled in.
Am I missing something here? I thought that the Haskell Report does not the comments semantics. They are the free floating entities, and can be put anywhere as it pleases a module developer. And we can have many possible types of comments describing: module, datatype, class, function, etc. Add to it some important decorations, delimiting some categories of functions, and we are in a complete mess. Granted the variety of styles used, how on earth even the cleverest parser can figure it out? Typical parsers (I am not talking here about HDoc) do not care because they skip the comments anyway but it is not the case for the documentation extractors. And the scheme: [(E1, C1), (E2, C2) ...] where (Ei,Ci) are pairs of top level entities and their associated comments, may work sometimes under the assumption that Ci always precedes Ei, but this is only the assumption which I can easily break anytime I wish: I can insert a category decoration somewhere in between or even reverse the order from Ci Ei to Ei Ci - what I often do because it pleases me so. This is the sad affair, because we could treat the problem the same way we treat the function signatures. The association between the function signatures (FSi) and their bodies (FBi) are not in any way positionally described. Sure, I have not seen a code whether someone writes: FS1 FS2 FS3 FB3 FB2 FB1, or FB1 FS1, but this is still OK - at least in Hugs, which I just checked to see if I am correct. There are few solutions possible: 1. Describe precise positional standard for placement of comments (see Eiffel (*) example) 2. Invent markups to identify comment types and their associations (see Java. But I am not talking here about the variable markups, etc. for a moment.) 3. Deliver development tools that force one particular layout and use its own internal markup system, but which is never visible to humans, unless they insist. (See Smalltalk browsers enforcing the style. Eiffel has it too, but admits old fashion editing, as long as the result conforms to the standard.) 4. Bite a bullet and admit that comments are as important as the code; extend Haskell Report to add those specialized comments to be part of the language ...... etc. All of those have their problems however. Jan P.S. Because our first few messages are not stored in the haskelldoc archive I am again showing the pointer to Eiffel online book. Chapters 1 and 5 talk about documentation issues. http://www-staff.socs.uts.edu.au/~rist/eiffel/ There are plenty of Eiffel sites. The oldest is the ISE site of Bertrand Meyer, the language inventor: http://www.eiffel.com