A Haskell Documentation Standard

[Simon Marlow]

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