[commit: ghc] master: Add -Wstar-is-type to the User's Guide (07083fc)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/07083fc44ebf3f0510ae1d71ae5c9c88c87ae1d8/ghc

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

commit 07083fc44ebf3f0510ae1d71ae5c9c88c87ae1d8
Author: Vladislav Zavialov <vlad.z.4096 at gmail.com>
Date:   Thu Oct 4 13:43:47 2018 -0400

    Add -Wstar-is-type to the User's Guide
    
    The -Wstar-is-type flag was added without documentation.
    Now it has documentation.
    
    Test Plan: Validate
    
    Reviewers: bgamari
    
    Reviewed By: bgamari
    
    Subscribers: rwbarton, carter
    
    Differential Revision: https://phabricator.haskell.org/D5203


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

07083fc44ebf3f0510ae1d71ae5c9c88c87ae1d8
 docs/users_guide/using-warnings.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index d93064b..dba30db 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -37,6 +37,7 @@ generally likely to indicate bugs in your program. These are:
     * :ghc-flag:`-Wtabs`
     * :ghc-flag:`-Wunrecognised-warning-flags`
     * :ghc-flag:`-Winaccessible-code`
+    * :ghc-flag:`-Wstar-is-type`
     * :ghc-flag:`-Wstar-binder`
 
 The following flags are simple ways to select standard "packages" of warnings:
@@ -1175,6 +1176,24 @@ of ``-W(no-)*``.
     since we're passing ``Foo1`` and ``Foo2`` here, it follows that ``t ~
     Char``, and ``u ~ Int``, and thus ``t ~ u`` cannot hold.
 
+.. ghc-flag:: -Wstar-is-type
+     :shortdesc: warn when ``*`` is used to mean ``Data.Kind.Type``
+     :type: dynamic
+     :reverse: -Wno-star-is-type
+     :category:
+
+     :since: 8.6
+
+     The use of ``*`` to denote the kind of inhabited types relies on the
+     :extension:`StarIsType` extension, which in a future release will be
+     turned off by default and then possibly removed. The reasons for this and
+     the deprecation schedule are described in `GHC proposal #30
+     <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst>`__.
+
+     This warning allows to detect such uses of ``*`` before the actual
+     breaking change takes place. The recommended fix is to replace ``*`` with
+     ``Type`` imported from ``Data.Kind``.
+
 .. ghc-flag:: -Wstar-binder
      :shortdesc: warn about binding the ``(*)`` type operator despite
          :ghc-flag:`-XStarIsType`