Add better support for default signatures in class definitions

[RyanGlScott]

Take two (see @mac-adder's #692 for take one). Fixes #439 and fixes #567.

This almost works without a hitch except for one glitch: Haddock has trouble finding documentation for a default signature. For instance, this file:

{-# LANGUAGE DefaultSignatures #-}

module DefaultSignatures where

-- | Documentation for Foo.
class Foo a where
  -- | Documentation for bar and baz.
  bar, baz :: a -> String

  -- | Documentation for the default signature of bar.
  default bar :: Show a => a -> String
  bar = show

  -- | Documentation for baz'.
  baz' :: String -> a

  -- | Documentation for the default signature of baz'.
  default baz' :: Read a => String -> a
  baz' = read

Gets rendered as:

Notice that the docstrings for the default signatures have been dropped. I've tried to determine why this is happening—it appears that Haddock drops all docstrings that aren't found in an AvailInfo, but default signatures don't correspond to AvailInfos. @alexbiehl, do you know how one might get that to work?

[harpocrates]

@RyanGlScott was the only known issue with this that the docstrings for default signatures are not found?

[RyanGlScott]

As far as I could see, yes.

[harpocrates]

This is a bit suspicious. That said, I think the smell is coming more from the fact that deriveUnique exists... and I don't see another easy workaround.

[harpocrates]

I've solved the issue around AvailInfo by manually looking up the docs for "uniquified" default methods names and putting them in the right ExportItem. The output of the test case now looks correct.

However, there is something else we had not considered: the Binary Name instance does not distinguish between name and uniquifyName name, so the interface file ends up containing docs for default method XOR docs for method. It looks like this clever hack is falling apart all too soon. We could probably work around this by patching the Binary InstalledInterface instance (ex. splitting docMap into docMap and docMapDefaults), but I suspect this is going to be a recurring source of confusion/bugs.

Thoughts?

[sjakobi]

However, there is something else we had not considered: the Binary Name instance does not distinguish between name and uniquifyName name, so the interface file ends up containing docs for default method XOR docs for method. It looks like this clever hack is falling apart all too soon. We could probably work around this by patching the Binary InstalledInterface instance (ex. splitting docMap into docMap and docMapDefaults), but I suspect this is going to be a recurring source of confusion/bugs.

If we split docMap, we'd have to split argMap too…

Maybe we can instead use a different key type for these maps.

Something like

data DocName = Name Name | DefaultSignatureName Name

maybe?

[sjakobi]

This should fix #30 too.

[RyanGlScott]

Was this subsumed by #938? If so, should this be closed?

[harpocrates]

There is still no support for documentation on default methods. #938 just ported over the HTML backend changes from this PR (basically parity with your original screenshot from here: #822 (comment)).

However, I'm now thoroughly convinced that the path forward to getting docs on default methods is going to involve their default method names (aka. isDefaultMethodOcc . occName returns True) and not some brittle hack involving "uniquified" names.

I don't think there is much more to gain from keeping this PR open (please re-open if you disagree).