haddock "leaks" the names of non exported type class methods in minimal complete definitions

[redneb]

I have a situation where a module defines a type class and it only exports the class but none of its methods. Despite that, haddock mentions the names of the non exported methods of the class as part of the minimal complete definition.
Here's an example:

module Foo (MyClass) where

class MyClass a where
    method1 :: a -> Int
    method2 :: a -> Int

    method2 = method1

Now, if I run haddock --hyperlink-source I get the following warning:

Warning: Foo: could not find link destinations for:
    Foo.method1

and the generated html documentation looks like that:

class MyClass a 
    Minimal complete definition
    method1

The name of the private method is also leaked in the hoogle documention.

I've tried this with haddock-2.15.0 under ghc-7.8.3.

[Fuuzetsu]

cc @haasn

[haasn]

This was a conscious decision - the idea is to let users know that implementing a class they see inside documentation would require implementing further methods that aren't visible on the page.

The guideline is that if the “minimal complete definition” box is empty, then you need to implement exactly what you see on the documentation page - no more, no less.

I'm not sure what to do about this issue. If we just hide the methods, won't that be potentially misleading? (Especially if it's a class that you can normally implement, like Foldable, but of which the module you're looking at only re-exports one method)

It would probably also possible to suppress this display by attaching an empty MINIMAL pragma, but that's unpleasant for other reasons.

[redneb]

I understand your point and I certainly wouldn't like it if the “minimal complete definition” box contains incorrect and misleading information. On the other hand, having abstract type classes is quite useful and I think haddock ought to handle them correctly. Here's an example: [1]. This class is abstract, it's not meant to be instantiable by users, and yet haddock reveals the internals of the implementation of the class, violating its abstractness.

[1] https://hackage.haskell.org/package/hxt-css-0.1.0.1/docs/Text-XML-HXT-CSS.html#t:Css

[ivan-m]

I too would prefer to not have Haddock reveal internal details of type classes that end users are not meant to be able to instantiate.

[Fuuzetsu]

Both @haasn and @redneb have valid points. Maybe we need a Haddock pragma or something (or abuse MINIMAL). Personally I agree with haasn here but clearly there are people who would like it to work other way. I'd be willing to consider a patch which allows both ways unless there is a strong argument for just one way (and code to back it).