ANNOUNCE: Haddock version 0.2, a Haskell documentation tool

[Simon Marlow]

> Just two remarks:
>=20
>     * The layout of documented constructors and record fields is a bit
>       heavyweight IMHO, almost a screenfull of lines for common
constructs.
>       I understand the current rationale, but nevertheless, does
anybody
>       have nice ideas for producing the more common "tabular" layout
found
>       in so many source files like:
>=20
>          data Blah =3D    -- The Blah type does blah blah blah...
>               Foo Int   -- Comment for Foo
>             | Bar Float -- Comment for Blah

Yes, this is one thing that could definitely be improved.  However, you
probably wouldn't want this kind of layout all the time - for example
when the comments were particularly long the currently layout mgiht be
more appropriate (IMHO).  Should it be possible to specify attributes
for declarations too, something like

    -- #tabular
    -- | doc for the 'Blah' type
    data Blah
       =3D Foo Int  -- | doc for 'Foo'
       | ...

or maybe it should switch to the tabular form automatically when the
comments are "small enough"?  There are one or two heuristics like this
already: eg. when there's no documentation on any of the constructors we
switch to a more compact rendering of the declaration.

>     * Having doc strings for function arguments would be high on my
>       personal wishlist. I know it's already in the TODO, and after
>       trying to implement it for myself and getting myriads of S/R
>       conflicts, I probably understand why it's still there...  :-]
>       The former remark would hold for this type of documentation,
>       too, BTW.

Ok, I'll have a think about how best to do this.  Any thoughts on what
the rendering should look like?  I'd considered something like this:

    foo ::
	<doc for the 'foo' function>
	     A   <doc for the A argument>
	  -> B   <doc for the B argument>
	  -> R   <doc for the return value>

or maybe the type should be given twice, like:

    foo :: A -> B -> R
	<doc for the 'foo' function>
	     A   <doc for the A argument>
	  -> B   <doc for the B argument>
	  -> R   <doc for the return value>

Anyway, thanks for the comments.

Cheers,
	Simon