ANN: Updating flag description in the User's Guide

[Jan Stolarek]

Devs,

I have some important information for everyone.

  TL;DR1 As a rule of thumb, whenever you modify DynFlags or StaticFlags please
  make absolutely sure that your changes are described in the User's Guide. See
  Note [Updating flag description in the User's Guide] in DynFlags.

  TL;DR2 Your help is needed to update the User's Guide.

I've spent last two days on updating the flag descriptions in the User's Guide
(#9358). Saying that things were a complete mess would be an understatement. We
had lots of flags that were not documented in the user's guide, we had
documentation for flags that no longer exist, lots of flags were incorrectly
labeled as static, etc. It seems that we don't have a habit of updating User's
Guide when we change the code responsible for flags. I updated huge chunks of
the documentation and things are in a better shape now. But if we forget to
update documentation when we make changes then in 2 or 3 years things will most
likely be as bad as they were before my clean-up. I added a Note and lots of
references to it to remind us about that. If things go well we might even have a
Herald rule to remind about updating User's Guide whenever DynFlags and
StaticFlags are modified by a commit/revision [1].

However, the task of updating flag descriptions in the User's Guide is not
finished. My main focus were the -f*/-fno-* optimisation flags described
primarily in sections 4.10 and 4.19.15 (note that HEAD has different section
numbers than 7.8.3). I updated what I could but there are still some
descriptions missing - I'm not familiar with some of flags that we have. Here's
where your help is required.

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. I suspect that -fkill-absence might be related to demand analysis -
CCing Nicolas Frisby.

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 (CCing Joachim)
  -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

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

  -fdicts-cheap
  -fdicts-strict
  -fdmd-tx-dict-sel (Nicolas, can you update that?)
  -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

These flags were deliberately omitted from the User's Guide because they are
deprectaed and will be removed:

  -fext-core
  -frewrite-rules

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)?

As part of my work I also removed -ddump-core-pipeline and -ddump-simpl-phases,
which weren;t very useful. And I cleaned up DynFlags by putting some of the long
lists of flags into alphabetical order. This change is a bit invasive - I'm
sorry if it causes merge conflicts, but I believe that in the long run this is
beneficial.

As I already said I focused primarily on -f* flags. But we should also make sure
that documentation of remaining flags is up to date, especially the -d* ones. I
don't have more time to put into this so I'm asking for a collective effort to
update the User's Guide, especially that we are moving closer to 7.10 release.

Janek

[1] https://phabricator.haskell.org/T52