[GHC] #9358: Improve flag description in the user guide

[GHC]

#9358: Improve flag description in the user guide
-------------------------------------+-------------------------------------
              Reporter:  jstolarek   |            Owner:
                  Type:  bug         |           Status:  new
              Priority:  normal      |        Milestone:  7.10.1
             Component:              |          Version:  7.8.3
  Documentation                      |         Keywords:
            Resolution:              |     Architecture:  Unknown/Multiple
      Operating System:              |       Difficulty:  Easy (less than 1
  Unknown/Multiple                   |  hour)
       Type of failure:              |       Blocked By:
  Documentation bug                  |  Related Tickets:  #1880
             Test Case:              |
              Blocking:              |
Differential Revisions:  Phab:D444   |
-------------------------------------+-------------------------------------
Changes (by jstolarek):

 * owner:  jstolarek =>
 * status:  closed => new
 * resolution:  fixed =>


Old description:

> Sections 4.20 (Flag reference) and 4.10.2 (-f*: platform-independent
> flags) of the User Guide could use some updating:
>
>   - `-floopification` is mentioned in 4.20 but not in 4.10.2 (which,
> sadly, is my fault),
>   - Section 4.10.2 says: "These flags turn on and off individual
> optimisations. They are normally set via the -O options (...) The flags
> below are off by default, except where noted below." Does the last
> sentence mean they are on by default for `-O` or that they are enabled
> even with `-O0` (which is the default optimisation level)?
>   - What is the default value of `-fmax-simplifier-iterations`?
>   - 4.20 mentions `-fmax-simplifier-iterations`, `-fmax-relevant-
> bindings` and `-fmax-worker-args` but only the first one is described in
> 4.10.2
>
> I suspect there are more inconsistencies.

New description:

 These flags are currently completely missing from the User's Guide:

   -fbuilding-cabal-package
   -fflat-cache
   -fhpc-no-auto
   -fkill-absence
   -fkill-one-shot
   -fsimple-list-literals
   -fspecialise-aggressively
   -fuse-rpaths
   -fspec-constr-recursive
   -ffloat-lam-args
   -ffloat-all-lams

 If you can provide description for any of these flags please edit
 flags.xml and using.xml.

 Following flags are listed in Flag Reference section (4.19) with a brief
 one sentence description but they don't have a detailed description in
 section 4.10 (using.xml):

   -fcall-arity
   -funfolding-fun-discount
   -funfolding-dict-discount
   -funfolding-keeness-factor
   -frule-check (see #9776)

 Following flags have a detailed description but it is confusing:

   -fdo-eta-reduction
   -fdo-lambda-eta-expansion

 Following flags have a description but it is too brief. We should have
 more
 details:

   -fdicts-cheap
   -fdicts-strict
   -fdmd-tx-dict-sel
   -fmax-inline-memcpy-insns
   -fmax-inline-memset-insns
   -fmax-worker-args
   -fno-opt-coercion
   -fno-pre-inlining
   -fsimplifier-phases
   -fspec-constr-threshold
   -fspec-constr-count
   -fstrictness-before

 For these flags Flag Reference section provides the description of their
 -fno-* version:

   -fembed-manifest
   -fgen-manifest
   -fghci-history
   -fghci-sandbox
   -fpre-inlining
   -fprint-bind-contents
   -fprof-count-entries
   -fshared-implib

 This seems to go against our convention of describing the flags. Should we
 revert to desribing their normal version (ie. ones that enable something,
 not disable)?

 We should also make sure that documentation of remaining flags is up to
 date, especially the -d* ones.

--

Comment:

 After some thought perhaps it's not a good idea to close this ticket. I'm
 changing the description to contain a list of flags to document and
 reopening.

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/9358#comment:22>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler