#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