ANNOUNCE: Haddock version 0.2, a Haskell documentation tool

[Manuel M. T. Chakravarty]

"Simon Marlow" <simonmar@microsoft.com> wrote,

> > Just two remarks:
> > 
> >     * 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:
> > 
> >          data Blah =    -- 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
>        = 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.

I'd prefer a heuristic depending on the size and/or layout
of the declaration over attributes.  (Or maybe a heuristic
that can be overridden by an attribute.)

Cheers,
Manuel