diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/users_guide/8.0.1-notes.rst | 18 | ||||
| -rw-r--r-- | docs/users_guide/glasgow_exts.rst | 28 | ||||
| -rw-r--r-- | docs/users_guide/using-warnings.rst | 46 |
3 files changed, 76 insertions, 16 deletions
diff --git a/docs/users_guide/8.0.1-notes.rst b/docs/users_guide/8.0.1-notes.rst index 6239ea5c52..b31223eef4 100644 --- a/docs/users_guide/8.0.1-notes.rst +++ b/docs/users_guide/8.0.1-notes.rst @@ -268,10 +268,20 @@ Compiler a warning when a pattern synonym definition doesn't have a type signature. It is turned off by default but enabled by :ghc-flag:`-Wall`. -- Changed the :ghc-flag:`-fwarn-unused-matches` flag to report unused type variables - in data and type families in addition to its previous behaviour. - To avoid warnings, unused type variables should be prefixed or replaced with - underscores. +- Added the :ghc-flag:`-Wunused-type-patterns` flag to report unused + type variables in data and type family instances. This flag is not implied + by :ghc-flag:`-Wall`, since :ghc-flag:`-Wunused-type-patterns` will + warn about unused type variables even if the types themselves are intended + to be used as documentation. If :ghc-flag:`-Wunused-type-patterns` is + enabled, one can prefix or replace unused type variables with underscores to + avoid warnings. + +- Split off the new flag :ghc-flag:`-Wunused-foralls` from the previously + existing flag :ghc-flag:`-Wunused-matches`. :ghc-flag:`-Wunused-foralls` + emits a warning in the specific case that a user writes explicit ``forall`` + syntax with unused type variables, while :ghc-flag:`-Wunused-matches` only + warns in the case of unused term-level patterns. Both flags are implied by + :ghc-flag:`-W`. - Added the :ghc-flag:`-Wtoo-many-guards` flag. When enabled, this will issue a warning if a pattern match contains too many guards (over 20 at the diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst index 6d02391c16..6ea2ef65df 100644 --- a/docs/users_guide/glasgow_exts.rst +++ b/docs/users_guide/glasgow_exts.rst @@ -6035,12 +6035,13 @@ declaration doesn't matter, it can be replaced with an underscore -- Equivalent to data instance F Int b = Int -When the flag :ghc-flag:`-fwarn-unused-matches` is enabled, type variables that are -mentioned in the patterns on the left hand side, but not used on the right -hand side are reported. Variables that occur multiple times on the left hand side -are also considered used. To suppress the warnings, unused variables should -be either replaced or prefixed with underscores. Type variables starting with -an underscore (``_x``) are otherwise treated as ordinary type variables. +When the flag :ghc-flag:`-Wunused-type-patterns` is enabled, type +variables that are mentioned in the patterns on the left hand side, but not +used on the right hand side are reported. Variables that occur multiple times +on the left hand side are also considered used. To suppress the warnings, +unused variables should be either replaced or prefixed with underscores. Type +variables starting with an underscore (``_x``) are otherwise treated as +ordinary type variables. This resembles the wildcards that can be used in :ref:`partial-type-signatures`. However, there are some differences. @@ -6193,9 +6194,10 @@ for data instances. For example, the ``[e]`` instance for ``Elem`` is :: Type arguments can be replaced with underscores (``_``) if the names of the arguments don't matter. This is the same as writing type variables -with unique names. Unused type arguments should be replaced or prefixed -with underscores to avoid warnings when the `-fwarn-unused-matches` flag -is enabled. The same rules apply as for :ref:`data-instance-declarations`. +with unique names. Unused type arguments can be replaced or prefixed +with underscores to avoid warnings when the +:ghc-flag:`-Wunused-type-patterns` flag is enabled. The same rules apply +as for :ref:`data-instance-declarations`. Type family instance declarations are only legitimate when an appropriate family declaration is in scope - just like class instances @@ -7701,6 +7703,14 @@ The two are treated identically. Of course ``forall`` becomes a keyword; you can't use ``forall`` as a type variable any more! +If the :ghc-flag:`-Wunused-foralls` flag is enabled, a warning will be emitted +when you write a type variable in an explicit ``forall`` statement that is +otherwise unused. For instance: :: + + g :: forall a b. (b -> b) + +would warn about the unused type variable `a`. + .. _flexible-contexts: The context of a type signature diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst index e4f8d2c3a7..afcee5b5d7 100644 --- a/docs/users_guide/using-warnings.rst +++ b/docs/users_guide/using-warnings.rst @@ -44,6 +44,7 @@ The following flags are simple ways to select standard "packages" of warnings: * :ghc-flag:`-Wunused-binds` * :ghc-flag:`-Wunused-matches` + * :ghc-flag:`-Wunused-foralls` * :ghc-flag:`-Wunused-imports` * :ghc-flag:`-Wincomplete-patterns` * :ghc-flag:`-Wdodgy-exports` @@ -871,14 +872,18 @@ of ``-W(no-)*``. single: unused matches, warning single: matches, unused - Report all unused variables which arise from pattern matches, - including patterns consisting of a single variable. This includes - unused type variables in type family instances. For instance + Report all unused variables which arise from term-level pattern matches, + including patterns consisting of a single variable. For instance ``f x y = []`` would report ``x`` and ``y`` as unused. The warning is suppressed if the variable name begins with an underscore, thus: :: f _x = True + Note that :ghc-flag:`-Wunused-matches` does not warn about variables which + arise from type-level patterns, as found in type family and data family + instances. This must be enabled separately through the + :ghc-flag:`-Wunused-type-patterns` flag. + .. ghc-flag:: -Wunused-do-bind .. index:: @@ -900,6 +905,41 @@ of ``-W(no-)*``. do { mapM_ popInt xs ; return 10 } +.. ghc-flag:: -Wunused-type-patterns + + .. index:: + single: unused type patterns, warning + single: type patterns, unused + + Report all unused type variables which arise from patterns in type family + and data family instances. For instance: :: + + type instance F x y = [] + + would report ``x`` and ``y`` as unused. The warning is suppressed if the + type variable name begins with an underscore, like so: :: + + type instance F _x _y = [] + + Unlike :ghc-flag:`-Wunused-matches`, :ghc-flag:`-Wunused-type-variables` is + not implied by :ghc-flag:`-Wall`. The rationale for this decision is that + unlike term-level pattern names, type names are often chosen expressly for + documentation purposes, so using underscores in type names can make the + documentation harder to read. + +.. ghc-flag:: -Wunused-foralls + + .. index:: + single: unused foralls, warning + single: foralls, unused + + Report all unused type variables which arise from explicit, user-written + ``forall`` statements. For instance: :: + + g :: forall a b c. (b -> b) + + would report ``a`` and ``c`` as unused. + .. ghc-flag:: -Wwrong-do-bind .. index:: |