[Git][ghc/ghc][wip/fixes-13] Improve docs on closed type families in hs-boots

[Rodrigo Mesquita (@alt-romes)]

Rodrigo Mesquita pushed to branch wip/fixes-13 at Glasgow Haskell Compiler / GHC


Commits:
722da428 by Rodrigo Mesquita at 2024-05-20T10:35:08+01:00
Improve docs on closed type families in hs-boots

Fixes #24776

- - - - -


2 changed files:

- docs/users_guide/exts/type_families.rst
- docs/users_guide/separate_compilation.rst


Changes:

=====================================
docs/users_guide/exts/type_families.rst
=====================================
@@ -415,10 +415,19 @@ left hand side of an equation can be explicitly bound, such as in: ::
 A closed type family may be declared with no equations. Such closed type
 families are opaque type-level definitions that will never reduce, are
 not necessarily injective (unlike empty data types), and cannot be given
-any instances. This is different from omitting the equations of a closed
-type family in a ``hs-boot`` file, which uses the syntax ``where ..``,
-as in that case there may or may not be equations given in the ``hs``
-file.
+any instances.
+
+In an ``hs-boot`` file, closed type families must either have the same
+equations as those in the source file, or you can use the following syntax to
+omit the equations (note the literal ``..``) ::
+
+  type family R a where ..
+
+In this case, the closed type family ``R`` matching this "boot" declaration may
+have any number of equations given in the source ``hs`` file (including zero).
+For more information on mutual recursive modules with ``hs-boot`` modules
+(including type families) see :ref:`mutual-recursion`.
+
 
 .. _type-family-examples:
 


=====================================
docs/users_guide/separate_compilation.rst
=====================================
@@ -729,8 +729,8 @@ be recompiled.
 
 .. _mutual-recursion:
 
-How to compile mutually recursive modules
------------------------------------------
+Mutually recursive modules and hs-boot files
+--------------------------------------------
 
 .. index::
    single: module system, recursion
@@ -851,8 +851,9 @@ A hs-boot file is written in a subset of Haskell:
 
 -  Open type and data family declarations are exactly as in Haskell.
 
--  A closed type family may optionally omit its equations, as in the
-   following example: ::
+-  A closed type family may either be given in full (where all equations must
+   match the source module), or it can be given abstractly using the ``where ..``
+   syntax (thus omitting the equations), as in the following example: ::
 
         type family ClosedFam a where ..
 



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/722da42823e43545cb61f13465b4579aa42f6fed

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/722da42823e43545cb61f13465b4579aa42f6fed
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240520/ae50bcf2/attachment-0001.html>