Hide instances that are "internal" to a module

[ross]

That is, instances where either the class or the type constructor is defined in the module but not exported.

[feuerbach]

I'm interested in implementing this, but not sure about the right semantics.

In particular, it seems to me that the right granularity is package, not module.

E.g. there might be an "internal" module which exports a datatype, which is an instance of an exported type class. If the datatype is not exported by any of the exposed modules, we don't want its existence to leak to the outside via this instance.

But haddock doesn't know about packages, as far as I understand. Any ideas on how to tackle this?

[SimonHengel]

I haven't verified, but my first guess would be that Cabal passes --hide=... for all modules that are not exported.

[feuerbach]

Thanks Simon, your guess was right.

I put two patches that should fix this ticket at https://github.com/feuerbach/haddock-1 (branch hiddenInstances). Could someone please review them?

They are based on ghc-7.4.1-release (for testing purposes), but it shouldn't be too hard to rebase them to the latest changes.

[SimonHengel]

I'm not doing the review, that is David's privilege. But I tried it, and it seems to work very well. One concern: if I understand correctly, the test case does not test correct handling of --hide at all, right? I think it would be possible to test this like so:

{-# OPTIONS_HADDOCK hide #-}
module Foo where

-- | Should be visible
class Foo a

-- | Should be visible
data Bar

-- | Should be visible
instance Foo Bar

-- | Should *not* be visible
data Baz

-- | Should *not* be visible
instance Foo Baz

module Bar (Foo, Bar) where
import Foo

[feuerbach]

if I understand correctly, the test case does not test correct handling of --hide at all, right?

That's true. Having a test as you suggested would be great indeed, but I don't think the current testing system supports multi-module tests. (Or maybe I'm wrong?)

[feuerbach]

Actually, Simon has already implemented the two-module test, which is now in my branch as well.

Apart from the fact that one more file now lacks a .ref file, it seems to work well.

[feuerbach]

Note: I renamed the repo, now it's https://github.com/feuerbach/haddock (branch hiddenInstances).

Btw, the patches are still there and waiting for a review.

[SimonHengel]

This will be include with 2.13.0.