RFC: style cleanup & guidelines for GHC, and related bikeshedding

[Simon Marlow]

On 03/07/2014 09:29, Simon Peyton Jones wrote:
> * A *primary* form of consumption is the source code itself.  I've found that
>    Haddock-compliant comments can be rather less readable in source code.
>    (Eg. CoreSyn.lhs where the #blah# notation coexists uneasily with Note [blah].)
>    So I'd be nervous of mandating Haddock-compliance.

I agree with this point, and it's why I always disliked literate source 
code: we only look at source code in a text editor, so using unwieldy 
markup compromises the most common use case.

But I don't think there was a proposal to use Haddock markup everywhere 
(e.g. Notes), only in function documentation.  Notes are for looking at 
in a text editor, so we can use whatever conventions we like.

Cheers,
Simon