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