Re: Haskell platform proposal: split package

21 Jul 2012

      (CCing David Waern, Haddocks maintainer)

On Sat, Jul 21, 2012 at 04:37:48PM +0200, Gábor Lehel wrote:
...
On Sat, Jul 21, 2012 at 2:13 PM, Simon Hengel  wrote:
...
...
An unrelated suggestion: you can give type signatures to the various
functions which are synonyms of each other as a group and they will
show up as a single item in the Haddocks.
Have you tried this a recent version of Haddock?  I think this was only
in the Haddock version that was released with GHC 7.2 (introduced due to
a change in GHC).  But it had issues with explicit export lists, so we
now always expand such signatures.
Cheers,
Simon
It seems to work with Haddock 2.10 / GHC 7.4.
Oh, then the patch did not make it into Haddock 2.10 / GHC 7.4.1.  But
Haddock 2.11 (which comes with GHC 7.4.2) expands such signatures.  The
corresponding ticket is at [1].
...
I remember I initially tried it with whatever old version of Haddock I
had installed and I was annoyed that it didn't work
AFAIK, prior to GHC 7.2, ghc did not retain that information in the AST
(see [2]).
...
(it got split into two declarations with one of them missing
documentation entirely -- quite suboptimal),
Maybe some solace, you now at least get the documentation on all the
declarations ;)
...
I would be sad if it stopped working again. :)
Some examples (which Hackage built using 7.4):
http://hackage.haskell.org/packages/archive/repa/3.2.1.1/doc/html/Data-Array...
(append, (++))
Looks like a valid use case.  I never thought about that, but if you
have synonyms for a function, it really makes sense. (Personally, I do
not really like synonyms, but for this particularly case even that makes
sense to me.)

The issue was with stuff like:

    Module Foo (

    -- * Foo
      foo

    -- * Bar
    , bar

    -- * Baz
    , baz
    ) where

    foo, bar, baz :: Int
    ...

Or what, if you change the order of identifiers in the export list?

There is an other case that would need special treatment.  We now
include deprecation messages for deprecated stuff in documentation.  So
for the following example the documentation for `foo` and `bar` would be
different:

    -- | Documentation for `foo` and `bar`.
    foo, bar :: Int
    {-# DEPRECATED foo "use `bar` instead" #-}
    ...

Cheers,
Simon

[1] http://trac.haskell.org/haddock/ticket/192
[2] http://hackage.haskell.org/trac/ghc/ticket/1595