[commit: ghc] master: Clarify topological sorting of spec vars in manual (3a7f204)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/3a7f204f5d713ed4ac034d371fc10d8bedb39efa/ghc

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

commit 3a7f204f5d713ed4ac034d371fc10d8bedb39efa
Author: Richard Eisenberg <eir at cis.upenn.edu>
Date:   Sun Jan 10 19:10:03 2016 -0500

    Clarify topological sorting of spec vars in manual
    
    This is mentioned in #11376.


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

3a7f204f5d713ed4ac034d371fc10d8bedb39efa
 docs/users_guide/glasgow_exts.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst
index 0ec5bd4..e77a7c0 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -2237,6 +2237,15 @@ Here are the details:
   will have its type variables
   ordered as ``m, a, b, c``.
 
+- If any of the variables depend on other variables (that is, if some
+  of the variables are *kind* variables), the variables are reordered
+  so that kind variables come before type variables, preserving the
+  left-to-right order as much as possible. That is, GHC performs a
+  stable topological sort on the variables.
+
+  For example: if we have ``bar :: Proxy (a :: (j, k)) -> b``, then
+  the variables are ordered ``j``, ``k``, ``a``, ``b``.
+
 - Class methods' type arguments include the class type
   variables, followed by any variables an individual method is polymorphic
   in. So, ``class Monad m where return :: a -> m a`` means