On Thu, Jul 3, 2014 at 6:29 PM, Simon Peyton Jones <simonpj@microsoft.com> wrote:
* Insisting on line comments exclusively, carries a cost.  The on-screen distraction
  of line comments, and the nuisance of writing them, is not trivial.  Perhaps it
  is bearable, but it's non-zero.  See example below.

I think you can use

{-|
Note [Extra dependencies from .hs-boot files]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Consider the following case:

  module A where
    import B
    data A1 = A1 B1

  module B where
    import {-# SOURCE #-} A
    type DisguisedA1 = A1
    data B1 = B1 DisguisedA1

We do not follow type synonyms when building the dependencies for each datatype,
so we will not find out that B1 really depends on A1 (which means it depends on
itself). To handle this problem, at the moment we add dependencies to everything
that comes from an .hs-boot file. But we don't add those dependencies to
everything. Imagine module B above had another datatype declaration:

  data B2 = B2 Int

Even though B2 has a dependency (on Int), all its dependencies are from things
that live on other packages. Since we don't have mutual dependencies across
packages, it is safe not to add the dependencies on the .hs-boot stuff to B2.

See also Note [Grouping of type and class declarations] in TcTyClsDecls.
-}

instead (skip the | after {- if you don't want it to be a Haddock comment).