[commit: ghc] ghc-8.0: Clarify topological sorting of spec vars in manual (eb09b29)

[git at git.haskell.org]

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

On branch  : ghc-8.0
Link       : http://ghc.haskell.org/trac/ghc/changeset/eb09b293d8b0700620098ecf9de6ac54c5bb8f0c/ghc

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

commit eb09b293d8b0700620098ecf9de6ac54c5bb8f0c
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.
    
    (cherry picked from commit 3a7f204f5d713ed4ac034d371fc10d8bedb39efa)


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

eb09b293d8b0700620098ecf9de6ac54c5bb8f0c
 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 0e52ffd..0b7696e 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