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.

* 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 :: 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 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