[ resending... mail problems at MS, sorry if you see this twice ] Hi All, Henrik - thanks for your comprehensive message! I've set up the mailing list on haskell.org (haskelldoc@haskell.org; go to http://www.haskell.org/mailman/listinfo/haskelldoc). Let's communicate on there from now on. My thoughts on the matter appear to differ slightly from yours and Jan's, so I'll try to express my own priorities for a documentation system. - we're all agreed that what is needed is an automatic documentation-generation tool that takes annotated Haskell and delivers documentation. It's important that we don't tie ourselves to one particular documentation format, so I believe we need a separately-specified format for the in-source documentation. This is one target for attack. - 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 :) - here's where we differ: instead of defining a new interface format and writing code to generate/parse the new format, I propose we define the format to be the same as Haskell source. Why? - we already have a pretty printer/parser for Haskell source. - we can start generating documentation from existing source straight away, without waiting for support from the compiler writers (who are generally a lazy bunch :-) It is true that by eliminating the compiler from the documentation path we lose the benefit of automatically derived types. However, the compiler often infers ugly types anyway (type synonyms may be expanded), and it's always good practice to give type signatures to every exported function. I bet there are very few functions in GHC's libraries that are exported without a type signature. Of course, I'm thinking more about "external" than "internal" documentation. But even for internal documentation, I don't think it would be a big loss not to get types if they weren't explicitly mentioned in the source. 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. I see the priorities as (a) getting the format for the documentation annotations specified, and (b) extending HDoc to do the business (and to add GHC extensions :). Cheers, Simon
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
participants (2)
-
Jan Skibinski -
Simon Marlow