Issue #18087: :since: for warnings of ghc 6/7/8

Added :since: fields to users_guide on warning, for warnings
introduced starting GHC 6.0.

The data was extracted from the HTML docs on warnings, see

  https://gitlab.haskell.org/ghc/ghc/-/issues/18087

and partially verified by consulting the change logs.

(cherry picked from commit 0b4033197c7f98aaf772025d7900ac3f9f8d958f)

Conflicts:
	docs/users_guide/using-warnings.rst

During merging, I also backported the -Wdefaults which exists at 9.0
but so far wasn't in the docs.

(cherry picked from commit b207ab013607e76b1214a772361b409c18cbd04c)

1 files changed, 149 insertions, 31 deletions

diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 7ba4244bd7..7f16e0a5ed 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -14,38 +14,47 @@ of warnings.
 To turn off an individual warning ``-W<wflag>``, use ``-Wno-<wflag>``.
 To reverse ``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
 
-By default, you get a standard set of warnings which are
-generally likely to indicate bugs in your program. These are:
-
-.. hlist::
-    :columns: 3
-
-    * :ghc-flag:`-Woverlapping-patterns`
-    * :ghc-flag:`-Wwarnings-deprecations`
-    * :ghc-flag:`-Wdeprecations`
-    * :ghc-flag:`-Wdeprecated-flags`
-    * :ghc-flag:`-Wunrecognised-pragmas`
-    * :ghc-flag:`-Wduplicate-exports`
-    * :ghc-flag:`-Wderiving-defaults`
-    * :ghc-flag:`-Woverflowed-literals`
-    * :ghc-flag:`-Wempty-enumerations`
-    * :ghc-flag:`-Wmissing-fields`
-    * :ghc-flag:`-Wmissing-methods`
-    * :ghc-flag:`-Wwrong-do-bind`
-    * :ghc-flag:`-Wsimplifiable-class-constraints`
-    * :ghc-flag:`-Wtyped-holes`
-    * :ghc-flag:`-Wdeferred-type-errors`
-    * :ghc-flag:`-Wpartial-type-signatures`
+.. ghc-flag:: -Wdefault
+    :shortdesc: enable default flags
+    :type: dynamic
+    :category:
+
+    :since: 8.0
+
     * :ghc-flag:`-Wunsupported-calling-conventions`
-    * :ghc-flag:`-Wdodgy-foreign-imports`
-    * :ghc-flag:`-Winline-rule-shadowing`
-    * :ghc-flag:`-Wunsupported-llvm-version`
-    * :ghc-flag:`-Wmissed-extra-shared-lib`
-    * :ghc-flag:`-Wtabs`
-    * :ghc-flag:`-Wunrecognised-warning-flags`
-    * :ghc-flag:`-Winaccessible-code`
-    * :ghc-flag:`-Wstar-binder`
-    * :ghc-flag:`-Wunicode-bidirectional-format-characters`
+
+    By default, you get a standard set of warnings which are
+    generally likely to indicate bugs in your program. These are:
+
+    .. hlist::
+        :columns: 3
+
+        * :ghc-flag:`-Woverlapping-patterns`
+        * :ghc-flag:`-Wwarnings-deprecations`
+        * :ghc-flag:`-Wdeprecations`
+        * :ghc-flag:`-Wdeprecated-flags`
+        * :ghc-flag:`-Wunrecognised-pragmas`
+        * :ghc-flag:`-Wduplicate-exports`
+        * :ghc-flag:`-Wderiving-defaults`
+        * :ghc-flag:`-Woverflowed-literals`
+        * :ghc-flag:`-Wempty-enumerations`
+        * :ghc-flag:`-Wmissing-fields`
+        * :ghc-flag:`-Wmissing-methods`
+        * :ghc-flag:`-Wwrong-do-bind`
+        * :ghc-flag:`-Wsimplifiable-class-constraints`
+        * :ghc-flag:`-Wtyped-holes`
+        * :ghc-flag:`-Wdeferred-type-errors`
+        * :ghc-flag:`-Wpartial-type-signatures`
+        * :ghc-flag:`-Wunsupported-calling-conventions`
+        * :ghc-flag:`-Wdodgy-foreign-imports`
+        * :ghc-flag:`-Winline-rule-shadowing`
+        * :ghc-flag:`-Wunsupported-llvm-version`
+        * :ghc-flag:`-Wmissed-extra-shared-lib`
+        * :ghc-flag:`-Wtabs`
+        * :ghc-flag:`-Wunrecognised-warning-flags`
+        * :ghc-flag:`-Winaccessible-code`
+        * :ghc-flag:`-Wstar-binder`
+        * :ghc-flag:`-Wunicode-bidirectional-format-characters`
 
 The following flags are simple ways to select standard "packages" of warnings:
 
@@ -106,6 +115,8 @@ The following flags are simple ways to select standard "packages" of warnings:
     :type: dynamic
     :category:
 
+    :since: 8.0
+
     Turns on every single warning supported by the compiler.
 
 .. ghc-flag:: -Wcompat
@@ -115,6 +126,8 @@ The following flags are simple ways to select standard "packages" of warnings:
     :reverse: -Wno-compat
     :category:
 
+    :since: 8.0
+
     Turns on warnings that will be enabled by default in the future, but remain
     off in normal compilations for the time being. This allows library authors
     eager to make their code future compatible to adapt to new features before
@@ -155,6 +168,8 @@ to abort.
     :reverse: -Wwarn
     :category:
 
+    :since: 6.8 (``-Wwarn``)
+
     Makes any warning into a fatal error. Useful so that you don't miss
     warnings when doing batch compilation. To reverse ``-Werror`` and stop
     treating any warnings as errors use ``-Wwarn``, or use ``-Wwarn=<wflag>``
@@ -226,6 +241,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unrecognised-warning-flags
     :category:
 
+    :since: 8.0
+
     :default: on
 
     Enables warnings when the compiler encounters a ``-W...`` flag that is not
@@ -238,6 +255,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-compat-unqualified-imports
     :category:
 
+    :since: 8.10
+
     Warns on qualified imports of core library modules which are subject to
     change in future GHC releases. Currently the following modules are covered
     by this warning:
@@ -258,6 +277,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-typed-holes
     :category:
 
+    :since: 7.8
+
     :default: on
 
     Determines whether the compiler reports typed holes warnings. Has no
@@ -272,6 +293,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-deferred-type-errors
     :category:
 
+    :since: 8.4
+
     Causes a warning to be reported when a type error is deferred until
     runtime. See :ref:`defer-type-errors`
 
@@ -321,6 +344,8 @@ of ``-W(no-)*``.
     :reverse: -fno-defer-out-of-scope-variables
     :category:
 
+    :since: 8.0
+
     Defer variable out-of-scope errors (errors about names without a leading underscore)
     until runtime. This will turn variable-out-of-scope errors into warnings.
     Using a value that depends on an out-of-scope variable produces a runtime error,
@@ -348,6 +373,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-partial-type-signatures
     :category:
 
+    :since: 7.10
+
     Determines whether the compiler reports holes in partial type
     signatures as warnings. Has no effect unless
     :extension:`PartialTypeSignatures` is enabled, which controls whether
@@ -373,6 +400,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unrecognised-pragmas
     :category:
 
+    :since: 6.10
+
     Causes a warning to be emitted when a pragma that GHC doesn't
     recognise is used. As well as pragmas that GHC itself uses, GHC also
     recognises pragmas known to be used by other tools, e.g.
@@ -387,6 +416,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missed-specialisations
     :category:
 
+    :since: 8.0
+
     Emits a warning if GHC cannot specialise an overloaded function, usually
     because the function needs an ``INLINABLE`` pragma. Reports when the
     situation arises during specialisation of an imported function.
@@ -407,6 +438,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-all-missed-specialisations
     :category:
 
+    :since: 8.0
+
     Emits a warning if GHC cannot specialise an overloaded function, usually
     because the function needs an ``INLINABLE`` pragma. Reports
     all such situations.
@@ -423,6 +456,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-warnings-deprecations
     :category:
 
+    :since: 6.10
+
     .. index::
        pair: deprecations; warnings
 
@@ -458,6 +493,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-noncanonical-monad-instances
     :category:
 
+    :since: 8.0
+
     Warn if noncanonical ``Applicative`` or ``Monad`` instances
     declarations are detected.
 
@@ -484,6 +521,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-noncanonical-monadfail-instances
     :category:
 
+    :since: 8.0
+
     Warn if noncanonical ``Monad`` or ``MonadFail`` instances
     declarations are detected.
 
@@ -512,6 +551,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-noncanonical-monoid-instances
     :category:
 
+    :since: 8.0
+
     Warn if noncanonical ``Semigroup`` or ``Monoid`` instances
     declarations are detected.
 
@@ -537,6 +578,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-monadfail-instances
     :category:
 
+    :since: 8.0
+
     .. index::
        single: MFP
        single: MonadFail Proposal
@@ -558,6 +601,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-semigroup
     :category:
 
+    :since: 8.0
+
     .. index::
        single: semigroup; warning
 
@@ -577,6 +622,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-deprecated-flags
     :category:
 
+    :since: 6.10
+
     .. index::
        single: deprecated flags
 
@@ -591,6 +638,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unsupported-calling-conventions
     :category:
 
+    :since: 7.6
+
     Causes a warning to be emitted for foreign declarations that use
     unsupported calling conventions. In particular, if the ``stdcall``
     calling convention is used on an architecture other than i386 then
@@ -602,6 +651,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-dodgy-foreign-import
     :category:
 
+    :since: 6.10
+
     Causes a warning to be emitted for foreign imports of the following
     form: ::
 
@@ -624,6 +675,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-dodgy-exports
     :category:
 
+    :since: 6.12
+
     Causes a warning to be emitted when a datatype ``T`` is exported
     with all constructors, i.e. ``T(..)``, but is it just a type
     synonym.
@@ -637,6 +690,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-dodgy-imports
     :category:
 
+    :since: 6.8
+
     Causes a warning to be emitted in the following cases:
 
     -  When a datatype ``T`` is imported with all constructors, i.e.
@@ -651,6 +706,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-overflowed-literals
     :category:
 
+    :since: 7.8
+
     Causes a warning to be emitted if a literal will overflow, e.g.
     ``300 :: Word8``.
 
@@ -660,6 +717,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-empty-enumerations
     :category:
 
+    :since: 7.8
+
     Causes a warning to be emitted if an enumeration is empty, e.g.
     ``[5 .. 3]``.
 
@@ -686,6 +745,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-duplicate-constraints
     :category:
 
+    :since: 7.8
+
     .. index::
        single: duplicate constraints, warning
 
@@ -790,6 +851,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-identities
     :category:
 
+    :since: 7.2
+
     Causes the compiler to emit a warning when a Prelude numeric
     conversion converts a type ``T`` to the same type ``T``; such calls are
     probably no-ops and can be omitted. The functions checked for are:
@@ -801,6 +864,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-implicit-kind-vars
     :category:
 
+    :since: 8.6
+
     .. index::
        single: implicit prelude, warning
 
@@ -819,6 +884,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-implicit-prelude
     :category:
 
+    :since: 6.8
+
     .. index::
        single: implicit prelude, warning
 
@@ -843,6 +910,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-incomplete-patterns
     :category:
 
+    :since: 5.04
+
     .. index::
        single: incomplete patterns, warning
        single: patterns, incomplete
@@ -867,6 +936,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-incomplete-uni-patterns
     :category:
 
+    :since: 7.2
+
     The flag :ghc-flag:`-Wincomplete-uni-patterns` is similar to
     :ghc-flag:`-Wincomplete-patterns`, except that it applies only to
     lambda-expressions and pattern bindings, constructs that only allow a
@@ -904,6 +975,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-incomplete-record-updates
     :category:
 
+    :since: 6.4
+
     .. index::
        single: incomplete record updates, warning
        single: record updates, incomplete
@@ -990,6 +1063,8 @@ of ``-W(no-)*``.
     :reverse: -fnowarn-missing-import-lists
     :category:
 
+    :since: 7.0
+
     .. index::
        single: missing import lists, warning
        single: import lists, missing
@@ -1050,6 +1125,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-exported-sigs
     :category:
 
+    :since: 7.10
+
     .. index::
        single: type signatures, missing
 
@@ -1063,6 +1140,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-exported-signatures
     :category:
 
+    :since: 8.0
+
     .. index::
        single: type signatures, missing
 
@@ -1080,6 +1159,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-local-sigs
     :category:
 
+    :since: 7.0
+
     .. index::
        single: type signatures, missing
 
@@ -1092,6 +1173,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-local-signatures
     :category:
 
+    :since: 8.0
+
     .. index::
        single: type signatures, missing
 
@@ -1106,6 +1189,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missing-pattern-synonym-signatures
     :category:
 
+    :since: 8.0
+
     .. index::
          single: type signatures, missing, pattern synonyms
 
@@ -1145,6 +1230,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-orphans
     :category:
 
+    :since: 6.4
+
     .. index::
        single: orphan instances, warning
        single: orphan rules, warning
@@ -1193,6 +1280,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-inaccessible-code
     :category:
 
+    :since: 8.6
+
     .. index::
        single: inaccessible code, warning
        single: inaccessible
@@ -1250,6 +1339,7 @@ of ``-W(no-)*``.
          :extension:`StarIsType`
      :type: dynamic
      :reverse: -Wno-star-binder
+     :since: 8.6
 
      Under :extension:`StarIsType`, a ``*`` in types is not an operator nor
      even a name, it is special syntax that stands for ``Data.Kind.Type``. This
@@ -1309,6 +1399,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-tabs
     :category:
 
+    :since: 6.8
+
     .. index::
        single: tabs, warning
 
@@ -1340,6 +1432,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-monomorphism-restriction
     :category:
 
+    :since: 6.8
+
     .. index::
        single: monomorphism restriction, warning
 
@@ -1357,6 +1451,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-monomorphism-restriction
     :category:
 
+    :since: 7.8
+
     Warn when using :ghc-flag:`-fllvm` with an unsupported version of LLVM.
 
 .. ghc-flag:: -Wmissed-extra-shared-lib
@@ -1365,6 +1461,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-missed-extra-shared-lib
     :category:
 
+    :since: 8.8
+
     Warn when GHCi can't load a shared lib it deduced it should load
     when loading a package and analyzing the extra-libraries stanza
     of the target package description.
@@ -1375,6 +1473,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unticked-promoted-constructors
     :category:
 
+    :since: 7.10
+
     .. index::
        single: promoted constructor, warning
 
@@ -1419,6 +1519,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-top-binds
     :category:
 
+    :since: 8.0
+
     .. index::
        single: unused binds, warning
        single: binds, unused
@@ -1453,6 +1555,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-local-binds
     :category:
 
+    :since: 8.0
+
     .. index::
        single: unused binds, warning
        single: binds, unused
@@ -1469,6 +1573,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-pattern-binds
     :category:
 
+    :since: 8.0
+
     .. index::
        single: unused binds, warning
        single: binds, unused
@@ -1533,6 +1639,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-do-bind
     :category:
 
+    :since: 6.12
+
     .. index::
        single: unused do binding, warning
        single: do binding, unused
@@ -1559,6 +1667,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-type-patterns
     :category:
 
+    :since: 8.0
+
     .. index::
        single: unused type patterns, warning
        single: type patterns, unused
@@ -1594,6 +1704,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unused-foralls
     :category:
 
+    :since: 8.0
+
     .. index::
        single: unused foralls, warning
        single: foralls, unused
@@ -1659,6 +1771,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-wrong-do-bind
     :category:
 
+    :since: 6.12
+
     .. index::
        single: apparently erroneous do binding, warning
        single: do binding, apparently erroneous
@@ -1688,6 +1802,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-inline-rule-shadowing
     :category:
 
+    :since: 7.8
+
     Warn if a rewrite RULE might fail to fire because the function might
     be inlined before the rule has a chance to fire. See
     :ref:`rules-inline`.
@@ -1710,6 +1826,8 @@ of ``-W(no-)*``.
     :reverse: -Wno-unbanged-strict-patterns
     :category:
 
+    :since: 8.2
+
     This flag warns whenever you write a pattern that binds a variable whose
     type is unlifted, and yet the pattern is not a bang pattern nor a bare variable.
     See :ref:`glasgow-unboxed` for information about unlifted types.