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

_______________________________________________
ghc-devs mailing list
ghc-devs@haskell.org
http://www.haskell.org/mailman/listinfo/ghc-devs