A Haskell Documentation Standard

[Armin Groesslinger]

On Wed, 31 Jan 2001, Simon Marlow wrote:

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

That means that classes and instances (and their functions) have to be
distinguished by giving the complete type of the class / instance
declaration, right?

E.g.

  class X a b where
     f :: a -> b

  instance X Person Frog where
     f x = ...

How do we avoid that the tool confuses the two version of "f" ?
An obvious way would be

     {-# DOC f INSTANCE X Person Frog ... #-}

     {-# DOC f CLASS    X             ... #-}


(HDoc required similar "help" in early versions, but I changed that in
 favour of considering positional information to reduce the redundancy
 required in the annotations.)


I guess additional annotations are an unavoidable drawback when not
relying on positional information. On the other hand, being able to put
the documentation in different files may be a big advantage.

So, should we allow both variants? I.e. use positional information when
the pragma happens to be next to a class/instance declaration (or a
function therein) and rely on extra information (like "CLASS X") in the
other case?


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

As flexibility should be a priority here (we want to produce many
different output formats, right?), I think XML is verbose, but not too
verbose. I don't see an alternative format which is significantly less
verbose. And, there's HaXml which could do a good job at processing the
documentation (I haven't had a very close look at HaXml, yet).


Regards,

Armin