[commit: ghc] wip/rae: Fix #11400, #11560 by documenting an infelicity. (37a52c3)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : wip/rae
Link       : http://ghc.haskell.org/trac/ghc/changeset/37a52c36db10d68460f14d86ac2da9a45e091726/ghc

>---------------------------------------------------------------

commit 37a52c36db10d68460f14d86ac2da9a45e091726
Author: Richard Eisenberg <rae at cs.brynmawr.edu>
Date:   Thu Jun 1 18:09:05 2017 -0400

    Fix #11400, #11560 by documenting an infelicity.
    
    Really, the fix for both of these is #11307.


>---------------------------------------------------------------

37a52c36db10d68460f14d86ac2da9a45e091726
 docs/users_guide/glasgow_exts.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index a2cc0ba..7fc075a 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -8347,9 +8347,9 @@ enabled).
 The only way ``*`` is unordinary is in its parsing. In order to be backward
 compatible, ``*`` is parsed as if it were an alphanumeric idenfifier; note
 that we do not write ``Int :: (*)`` but just plain ``Int :: *``. Due to the
-bizarreness with which ``*`` is parsed-and the fact that it is the only such
-operator in GHC-there are some corner cases that are
-not handled. We are aware of two:
+bizarreness with which ``*`` is parsed--and the fact that it is the only such
+operator in GHC--there are some corner cases that are
+not handled. We are aware of three:
 
 - In a Haskell-98-style data constructor, you must put parentheses around
   ``*``, like this: ::
@@ -8363,6 +8363,10 @@ not handled. We are aware of two:
   Note that the keyword ``type`` there is just to disambiguate the import
   from a term-level ``(*)``. (:ref:`explicit-namespaces`)
 
+- In an instance declaration head (the part after the word ``instance``), you
+  must parenthesize ``*``. This applies to all manners of instances, including
+  the left-hand sides of individual equations of a closed type family.
+
 The ``Data.Kind`` module also exports ``Type`` as a synonym for ``*``.
 Now that type synonyms work in kinds, it is conceivable that we will deprecate
 ``*`` when there is a good migration story for everyone to use ``Type``.