Explain -XAllowAmbiguousTypes suggestion

[JakobBruenker]

Summary

GHC's occasional suggestion to enable -XAllowAmbiguousTypes can be misleading and would benefit from being documented.

Motivation

A few years ago, Richard Eisenberg mentioned that it would be great if GHC error messages could refer users to web pages.

We have that now! But the context in which he mentioned it was the suggestion GHC makes to enable -XAllowAmbiguousTypes. It looks like this:

-- example to trigger the error
normalForm :: forall a . (Show a, Read a) => String -> String
normalForm = show @a . read @a

error: [GHC-39999]
    * Could not deduce `Show a0'
      from the context: (Show a, Read a)
    * In the ambiguity check for `normalForm'
      To defer the ambiguity check to use sites, enable AllowAmbiguousTypes

In this case, it would be appropriate - though perhaps not optimal - to use -XAllowAmbiguousTypes, though it can also creep up in cases where enabling the suggestion is a red herring. Helping users to figure out which is which is likely to be useful.

Suggested Documentation

I have not gotten around to making a precise wording yet, but here are some things I think could be interesting for users:

• One example where the extension helps, and one where GHC's suggestion is unhelpful
• An example of how to solve it with -XRequiredTypeArguments instead, added in GHC 9.10, which provides an alternative for most previously mandatory uses of -XAllowAmbiguousTypes.

Challenges

The example above links us to error GHC-39999.

But let's look at another example:

type family F a

f :: F a
f = 4

Here, we get the error

error: [GHC-83865]
    * Couldn't match expected type: F a
                  with actual type: F a0
      NB: `F' is a non-injective type family
      The type variable `a0' is ambiguous
    * In the ambiguity check for `f'
      To defer the ambiguity check to use sites, enable AllowAmbiguousTypes

The same suggestion - but this is an entirely different error, GHC-83865!

So the suggestion really is somewhat orthogonal to the error itself.

There at least two ways to address this:

1. Simply place the explanation on both pages
   • Pros: Simple
   • Cons: Annoying to maintain, maybe not relevant enough for those error messages in general for their pages to be this explanation's proper home
2. Add a link specific to the suggestion to the error message, rather than only having the error number itself. This would require coordination with GHC. I imagine this does not make much sense if -XAllowAmbiguousTypes is a special case, but maybe a mechanism like this could have more use cases, either generally for suggestions that can appear in error messages, or for things that are relevant to multiple error messages