Do not warn about private link to private symbols

[guibou]

The following:

module Private (
  bar,
  Foo(a),
  ) where

-- | 'foo' is really great, and uses 'bar'. This reference to 'foo'
-- will triggers a warning when it is actually never used in the final
-- document, because this documentation is private.
foo = undefined

bar = undefined

class Foo t where
  a :: t
  b :: t

Leads to the following warnings when using haddock Private.hs:

Warning: Private: could not find link destinations for:
    b foo

• The link to foo cannot be resolved because the documentation for foo won't be exported. However the link to foo is inside an unexported piece of documentation, so this is not an issue. I then consider that this warning can be discarded.
• The link to b will appear in the minimal complete definition exported for Foo. I agree that b appears on the minimal complete definition (see haddock "leaks" the names of non exported type class methods in minimal complete definitions #330), but a warning should not be generated. I also think that the documentation must explicitly say that b is not exported, with something such as Minimal complete definition: a, b (private).

These warnings are especially annoying in continuous integration where we want to fail if haddock returns any warning. See for example the work of #927.

This was tested with ghc 8.8.1 (currently in rc status). Similar results appears with ghc 8.6.5.

[guibou]

cc @ghorn

[guibou]

Note that due to these bugs, it is close to impossible to build a warning free documentation because a few base elements triggers theses warnings.

[harpocrates]

Thanks for the bug report! I agree with everything you pointed out.

[guibou]

Note that an easy workaround is to:

• export the missing symbols
• Do not make any link to the hidden symbol in hidden documentation (or do not write hidden haddock). This does not work for the class functions.

[harpocrates]

I've been thinking about this a bit more.

• The minimal complete definition is a bit of an edge case. We can fix it with some custom code and maybe we should.

• The link to the hidden symbol is an interesting manifestation of another problem: Haddock doesn't have a good way of keeping track of which docs will somehow get used, so it processes every docstring (and during renaming, warns about there not being a link destination).

  I think we should figure out how to filter out docstrings for "private" names earlier. We shouldn't have to do any work on docstrings (including the link resolution that triggers the warning from this issue) if they aren't even used. Fun fact: although the hidden docstrings don't show up in the docs, they show up in the *.haddock interface files!