What about standardizing on an 'experimental' prefix such as -fx-use-rpaths or -fx-kill-oneshot? These flags would not be added to the user guide and their intent clear when actually using them.
On Thu, Nov 6, 2014 at 10:28 AM, Simon Marlow <[email protected]> wrote: > 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 > [email protected] > http://www.haskell.org/mailman/listinfo/ghc-devs >
_______________________________________________ ghc-devs mailing list [email protected] http://www.haskell.org/mailman/listinfo/ghc-devs
