ANN: Updating flag description in the User's Guide

[Simon Marlow]

On 06/11/2014 12:06, Jan Stolarek wrote:
> 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].

Your efforts are much appreciated, thankyou :)

> 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

Sometimes we add flags that are for experimentation or development 
purposes and not intended for user consumption, and these tend not to be 
added to the User's Guide.  I suspect many of the flags you mention fall 
into this category.  I suggest for these we have a specific comment in 
the source "developer use only; undocumented" so that we know they don't 
need to go in the User's Guide.

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

Flags that are on by default we often document the no- version 
deliberately, because this is the form the user is most likely to want. 
  Documenting the positive version sounds strange and is likely to be 
confusing.  I'm surprised you didn't include -fomit-yields here.

> As part of my work I also removed -ddump-core-pipeline and -ddump-simpl-phases,

isn't -ddump-simpl-phases useful?  what's the other way to do that?

Cheers,
Simon