Doc: Fix out-of-sync using-optimisation page

- Make explicit that default flag values correspond to their -O0 value.
- Fix -fignore-interface-pragmas, -fstg-cse, -fdo-eta-reduction,
  -fcross-module-specialise, -fsolve-constant-dicts, -fworker-wrapper.

1 files changed, 40 insertions, 37 deletions

diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index df87fdb6a3..c75d5e6097 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -117,9 +117,9 @@ The easiest way to see what ``-O`` (etc.) “really mean” is to run with
    single: -fno-\* options (GHC)
 
 These flags turn on and off individual optimisations. Flags marked as
-on by default are enabled by ``-O``, and as such you shouldn't
-need to set any of them explicitly. A flag ``-fwombat`` can be negated
-by saying ``-fno-wombat``.
+*on* by default are enabled at all optimisation levels by default, and
+as such you shouldn't need to set any of them explicitly. A flag
+``-fwombat`` can be negated by saying ``-fno-wombat``.
 
 .. ghc-flag:: -fcore-constant-folding
     :shortdesc: Enable constant folding in Core. Implied by :ghc-flag:`-O`.
@@ -127,7 +127,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-core-constant-folding
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables Core-level constant folding, i.e. propagation of values
     that can be computed at compile time.
@@ -138,7 +138,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-case-merge
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Merge immediately-nested case expressions that scrutinise the same variable.
     For example, ::
@@ -162,7 +162,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-case-folding
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Allow constant folding in case expressions that scrutinise some primops:
     For example, ::
@@ -185,7 +185,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-call-arity
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enable call-arity analysis.
 
@@ -195,7 +195,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-exitification
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables the floating of exit paths out of recursive functions.
 
@@ -205,7 +205,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cmm-elim-common-blocks
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables the common block elimination optimisation
     in the code generator. This optimisation attempts to find identical
@@ -217,7 +217,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cmm-sink
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables the sinking pass in the code generator.
     This optimisation attempts to find identical Cmm blocks and
@@ -231,7 +231,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cmm-static-pred
     :category:
 
-    :default: off but enabled with :ghc-flag:`-O`.
+    :default: off but enabled by :ghc-flag:`-O`.
 
     This enables static control flow prediction on the final Cmm
     code. If enabled GHC will apply certain heuristics to identify
@@ -244,7 +244,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cmm-control-flow
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables some control flow optimisations in the Cmm code
     generator, merging basic blocks and avoiding jumps right after jumps.
@@ -255,7 +255,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-asm-shortcutting
     :category:
 
-    :default: off
+    :default: off but enabled by :ghc-flag:`-O2`.
 
     This enables shortcutting at the assembly stage of the code generator.
     In simpler terms shortcutting means if a block of instructions A only consists
@@ -268,12 +268,12 @@ by saying ``-fno-wombat``.
     does nothing on macOS.
 
 .. ghc-flag:: -fblock-layout-cfg
-    :shortdesc: Use the new cfg based block layout algorithm.
+    :shortdesc: Use the new cfg based block layout algorithm. Implied by :ghc-flag:`-O`.
     :type: dynamic
     :reverse: -fno-block-layout-cfg
     :category:
 
-    :default: off but enabled with :ghc-flag:`-O`.
+    :default: off but enabled by :ghc-flag:`-O`.
 
     The new algorithm considers all outgoing edges of a basic blocks for
     code layout instead of only the last jump instruction.
@@ -326,7 +326,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cpr-anal
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Turn on CPR analysis, which enables the worker/wrapper transformation (cf.
     :ghc-flag:`-fworker-wrapper`) to unbox the result of a function, such as ::
@@ -386,7 +386,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-cse
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables the common-sub-expression elimination
     optimisation. Switching this off can be useful if you have some
@@ -394,12 +394,12 @@ by saying ``-fno-wombat``.
 
 .. ghc-flag:: -fstg-cse
     :shortdesc: Enable common sub-expression elimination on the STG
-        intermediate language
+        intermediate language. Implied by :ghc-flag:`-O`.
     :type: dynamic
     :reverse: -fno-stg-cse
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Enables the common-sub-expression elimination optimisation on the STG
     intermediate language, where it is able to common up some subexpressions
@@ -422,7 +422,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-dicts-strict
     :category:
 
-    :default: off
+    :default: off but enabled by :ghc-flag:`-O2`.
 
     Make dictionaries strict.
 
@@ -447,7 +447,7 @@ by saying ``-fno-wombat``.
     Behaviour is unconditionally enabled starting with 9.2
 
 .. ghc-flag:: -fdo-eta-reduction
-    :shortdesc: Enable eta-reduction. Implied by :ghc-flag:`-O`.
+    :shortdesc: Enable eta-reduction. Always enabled by default.
     :type: dynamic
     :reverse: -fno-do-eta-reduction
     :category:
@@ -518,7 +518,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-float-in
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Float let-bindings inwards, nearer their binding
     site. See `Let-floating: moving bindings to give faster programs
@@ -544,7 +544,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-full-laziness
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Run the full laziness optimisation (also known as
     let-floating), which floats let-bindings outside enclosing lambdas,
@@ -591,7 +591,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-ignore-asserts
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Causes GHC to ignore uses of the function ``Exception.assert`` in source
     code (in other words, rewriting ``Exception.assert p e`` to ``e`` (see
@@ -603,7 +603,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-ignore-interface-pragmas
     :category:
 
-    :default: off
+    :default: Implied by :ghc-flag:`-O0`, otherwise off.
 
     Tells GHC to ignore all inessential information when reading
     interface files. That is, even if :file:`M.hi` contains unfolding or
@@ -632,7 +632,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-liberate-case
     :category:
 
-    :default: off but enabled with :ghc-flag:`-O2`.
+    :default: off but enabled by :ghc-flag:`-O2`.
 
     Turn on the liberate-case transformation. This unrolls recursive function
     once in its own RHS, to avoid repeated case analysis of free variables. It's
@@ -657,7 +657,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-loopification
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     When this optimisation is enabled the code generator will turn all
     self-recursive saturated tail calls into local jumps rather than
@@ -1074,7 +1074,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-specialise
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Specialise each type-class-overloaded function
     defined in this module for the types at which it is called in this
@@ -1101,12 +1101,12 @@ by saying ``-fno-wombat``.
 
 .. ghc-flag:: -fcross-module-specialise
     :shortdesc: Turn on specialisation of overloaded functions imported from
-        other modules.
+        other modules. Implied by :ghc-flag:`-O`.
     :type: dynamic
     :reverse: -fno-cross-module-specialise
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Specialise ``INLINABLE`` (:ref:`inlinable-pragma`)
     type-class-overloaded functions imported from other modules for the types at
@@ -1136,7 +1136,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-inline-generics
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
     :since: 9.2.1
 
     .. index::
@@ -1175,12 +1175,12 @@ by saying ``-fno-wombat``.
 
 .. ghc-flag:: -fsolve-constant-dicts
     :shortdesc: When solving constraints, try to eagerly solve
-        super classes using available dictionaries.
+        super classes using available dictionaries. Implied by :ghc-flag:`-O`.
     :type: dynamic
     :reverse: -fno-solve-constant-dicts
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     When solving constraints, try to eagerly solve
     super classes using available dictionaries.
@@ -1229,7 +1229,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-stg-lift-lams
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O2`.
 
     Enables the late lambda lifting optimisation on the STG
     intermediate language. This selectively lifts local functions to
@@ -1281,7 +1281,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-strictness
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     Turn on demand analysis.
 
@@ -1441,7 +1441,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-unbox-small-strict-fields
     :category:
 
-    :default: on
+    :default: off but enabled by :ghc-flag:`-O`.
 
     .. index::
        single: strict constructor fields
@@ -1654,10 +1654,13 @@ by saying ``-fno-wombat``.
 
 
 .. ghc-flag:: -fworker-wrapper
-    :shortdesc: Enable the worker/wrapper transformation.
+    :shortdesc: Enable the worker/wrapper transformation. Implied by :ghc-flag:`-O`
+        and by :ghc-flag:`-fstrictness`.
     :type: dynamic
     :category:
 
+    :default: off but enabled by :ghc-flag:`-O`.
+
     Enable the worker/wrapper transformation after a demand analysis pass.
 
     Exploits strictness and absence information by unboxing strict arguments