[commit: ghc] master: user-guide: Clarify default optimization flags (2c23fff)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/2c23fff2e03e77187dc4d01f325f5f43a0e7cad2/ghc

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

commit 2c23fff2e03e77187dc4d01f325f5f43a0e7cad2
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Wed Oct 25 15:53:40 2017 -0400

    user-guide: Clarify default optimization flags
    
    Begins to fix #14214.
    
    [skip ci]
    
    Test Plan: Read it.
    
    Reviewers: austin
    
    Subscribers: rwbarton, thomie
    
    GHC Trac Issues: #14214
    
    Differential Revision: https://phabricator.haskell.org/D4098


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

2c23fff2e03e77187dc4d01f325f5f43a0e7cad2
 docs/users_guide/using-optimisation.rst | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/users_guide/using-optimisation.rst b/docs/users_guide/using-optimisation.rst
index 763c778..ccf9ac5 100644
--- a/docs/users_guide/using-optimisation.rst
+++ b/docs/users_guide/using-optimisation.rst
@@ -52,7 +52,6 @@ So, for example, ``ghc -c Foo.hs``
 .. ghc-flag:: -O0
     :shortdesc: Disable optimisations (default)
     :type: dynamic
-    :reverse: -O
     :category: optimization-levels
 
     Means "turn off all optimisation", reverting to the same settings as
@@ -584,7 +583,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: coercion optimisation enabled.
 
     Turn off the coercion optimiser.
 
@@ -593,7 +592,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: pre-inlining enabled
 
     Turn off pre-inlining.
 
@@ -604,7 +603,7 @@ by saying ``-fno-wombat``.
     :type: dynamic
     :category:
 
-    :default: off
+    :default: state hack is enabled
 
     Turn off the "state hack" whereby any lambda with a ``State#`` token
     as argument is considered to be single-entry, hence it is considered
@@ -617,7 +616,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-omit-interface-pragmas
     :category:
 
-    :default: off
+    :default: Implied by :ghc-flag:`-O0`, otherwise off.
 
     Tells GHC to omit all inessential information from the interface
     file generated for the module being compiled (say M). This means
@@ -634,7 +633,7 @@ by saying ``-fno-wombat``.
     :reverse: -fno-omit-yields
     :category:
 
-    :default: on
+    :default: yield points enabled
 
     Tells GHC to omit heap checks when no allocation is
     being performed. While this improves binary sizes by about 5%, it
@@ -652,6 +651,8 @@ by saying ``-fno-wombat``.
     :reverse: -fno-pedantic-bottoms
     :category:
 
+    :default: off
+
     Make GHC be more precise about its treatment of bottom (but see also
     :ghc-flag:`-fno-state-hack`). In particular, stop GHC eta-expanding through
     a case expression, which is good for performance, but bad if you are