[commit: ghc] master: A few remarks on role subtyping in the manual. (2f115a1)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2f115a13a0fab84f6bc384c9b6159f29ea038d36/ghc

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

commit 2f115a13a0fab84f6bc384c9b6159f29ea038d36
Author: Edward Z. Yang <ezyang at cs.stanford.edu>
Date:   Mon Mar 6 15:22:37 2017 -0800

    A few remarks on role subtyping in the manual.
    
    Signed-off-by: Edward Z. Yang <ezyang at cs.stanford.edu>


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

2f115a13a0fab84f6bc384c9b6159f29ea038d36
 docs/users_guide/separate_compilation.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/users_guide/separate_compilation.rst b/docs/users_guide/separate_compilation.rst
index 743822f..a140d46 100644
--- a/docs/users_guide/separate_compilation.rst
+++ b/docs/users_guide/separate_compilation.rst
@@ -917,11 +917,17 @@ to ``hs-boot`` files, but with some slight changes:
   relation ``phantom < representational < nominal``: for example,
   an abstract type with a nominal type parameter can be implemented
   using a concrete type with a representational type parameter.
+  Merging respects this subtyping relation (e.g., ``nominal``
+  merged with ``representational`` is ``representational``.)
   Roles in signatures default to ``nominal``, which gives maximum
   flexibility on the implementor's side.  You should only need to
   give an explicit role annotation if a client of the signature
   would like to coerce the abstract type in a type parameter (in which case you
-  should specify ``representational`` explicitly.)
+  should specify ``representational`` explicitly.)  Unlike
+  regular data types, we do *not* assume that abstract
+  data types are representationally injective: if we have
+  ``Coercible (T a) (T b)``, and ``T`` has role ``nominal``,
+  this does not imply that ``a ~ b``.
 
 - A class declarations can either be abstract or concrete.  An
   abstract class is one with no superclasses or class methods::
@@ -990,6 +996,8 @@ to ``hs-boot`` files, but with some slight changes:
 
 Known limitations:
 
+- Pattern synonyms are not supported.
+
 - Algebraic data types specified in a signature cannot be implemented using
   pattern synonyms.  See :ghc-ticket:`12717`