A Haskell Documentation Standard

[Simon Marlow]

Jan Sibinki writes:

> 	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.

Sorry for not being clear about this.  You're right in that trying to
understand arbitrary comments in Haskell source isn't workable.  The
documentation annotations must be in a special format that the
documentation tool can understand.

eg.  HDoc's {--- .. -} style comments.  I had in mind using Haskell's
pragma convention, like this:

{-# DOC f
    <desc><id>f</id> turns people into frogs</desc>
    <arg><id>x</id> A <type>Person</type></arg>
    <ret>A <type>Frog</type></ret>
#-}
f :: Person -> Frog
f x = ...

with similar annotations for classes, instances, datatypes, newtypes
etc.  There's no requirement that the documentation appears directly
before the source code for the function; since it contains the
identifier of the entity being documented, it can be placed anywhere
(even in a different file).

The markup format for the documentation is of course up for discussion.
XML seems plausible but verbose.

If I understand correctly, I think you were proposing a two stage
process to get the documentation (similar to the Eiffel approach?):

	Haskell source --> interface ---> on-line documentation
                                   `--> printed documentation
                                        .....

Why not do it in one?

	Haskell source ---> on-line documentation
			   `--> printed documentation
                          ....

Cheers,
	Simon