[commit: ghc] wip/rae: Clarify topological sorting of spec vars in manual (9e59c7a)

[git at git.haskell.org]

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

On branch  : wip/rae
Link       : http://ghc.haskell.org/trac/ghc/changeset/9e59c7a0c8d6a195bee9172b6cddb9dc6d3547e8/ghc

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

commit 9e59c7a0c8d6a195bee9172b6cddb9dc6d3547e8
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.


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

9e59c7a0c8d6a195bee9172b6cddb9dc6d3547e8
 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 f53478d..4cbc36a 100644
--- a/docs/users_guide/glasgow_exts.rst
+++ b/docs/users_guide/glasgow_exts.rst
@@ -2215,6 +2215,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