Document operator sections' interaction with subsumptionwip/T19457

This resolves #19457 by making a note of breaking changes (introduced in
GHC 9.2) to the way that GHC typechecks operator sections where the operator
has nested `forall`s or contexts in its type signature.

2 files changed, 19 insertions, 0 deletions

diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst
index 5e0bf1c317..521427b4d9 100644
--- a/docs/users_guide/9.2.1-notes.rst
+++ b/docs/users_guide/9.2.1-notes.rst
@@ -65,6 +65,21 @@ Language
     record pattern synonyms.  In particular, it is possible for a single module
     to define multiple pattern synonyms using the same field names.
 
+* Because of simplifications to the way that GHC typechecks operator sections,
+  operators with nested ``forall``\ s or contexts in their type signatures might
+  not typecheck when used in a section. For instance, the ``g`` function below,
+  which was accepted in previous GHC releases, will no longer typecheck: ::
+
+      f :: a -> forall b. b -> a
+      f x _ = x
+
+      g :: a -> a
+      g = (`f` "hello")
+
+  ``g`` can be made to typecheck once more by eta expanding it to
+  ``\x -> x \`f\` "hello"``. For more information, see
+  :ref:`simple-subsumption`.
+
 Compiler
 ~~~~~~~~
 
diff --git a/docs/users_guide/exts/rank_polymorphism.rst b/docs/users_guide/exts/rank_polymorphism.rst
index 648ce40a70..8e9f55dd5b 100644
--- a/docs/users_guide/exts/rank_polymorphism.rst
+++ b/docs/users_guide/exts/rank_polymorphism.rst
@@ -195,6 +195,10 @@ Similarly ``f4 g4`` is not well typed, because the constraints appear in a diffe
 These examples can be made to typecheck by eta-expansion. For example ``f3 (\x -> g3b x)``
 is well typed, and similarly ``f3 (\x -> g3c x)`` and ``f4 (\x -> g4 x)``.
 
+A similar phenomenon occurs for operator sections. For example,
+``(\`g3a\` "hello")`` is not well typed, but it can be made to typecheck by eta
+expanding it to ``\x -> x \`g3a\` "hello"``.
+
 Historical note.  Earlier versions of GHC allowed these now-rejected applications, by inserting
 automatic eta-expansions, as described in Section 4.6 of `Practical type inference for arbitrary-aank types <https://www.microsoft.com/en-us/research/publication/practical-type-inference-for-arbitrary-rank-types/>`__, where it is
 called "deep skolemisation".