Add -Wstar-is-type to the User's Guide
authorVladislav Zavialov <vlad.z.4096@gmail.com>
Thu, 4 Oct 2018 17:43:47 +0000 (13:43 -0400)
committerBen Gamari <ben@smart-cactus.org>
Sat, 13 Oct 2018 03:32:49 +0000 (23:32 -0400)
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

(cherry picked from commit 07083fc44ebf3f0510ae1d71ae5c9c88c87ae1d8)

docs/users_guide/using-warnings.rst

index 2643f8f..d2a39df 100644 (file)
@@ -34,6 +34,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:
@@ -1188,6 +1189,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`