ANN: Updating flag description in the User's Guide
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
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
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
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
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. As already stated in an earlier reply I think we should have documentation for the sake of other developers.
I don't like the idea of separate prefix for experimental flags. This could be problematic when the flag becomes stable - we would have to change its name and that would break backwards compatibility. Janek
Agreed. For example, the HTTP standard has moved away from X-prefixed
headers for similar reasons.
On Thu, Nov 6, 2014 at 2:13 PM, Jan Stolarek
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. As already stated in an earlier reply I think we should have documentation for the sake of other developers.
I don't like the idea of separate prefix for experimental flags. This could be problematic when the flag becomes stable - we would have to change its name and that would break backwards compatibility.
Janek _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
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. I don't like that policy. What if some of the mentioned flags could be useful for my development work but I have no idea how to use these flags because they are not documented? I think we should have these documented as well, possibly with a note saying that this is experimental/unstable.
isn't -ddump-simpl-phases useful? what's the other way to do that? I'll reply in a thread started by Johan.
Janek
On 06/11/2014 13:02, Jan Stolarek wrote:
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. I don't like that policy. What if some of the mentioned flags could be useful for my development work but I have no idea how to use these flags because they are not documented? I think we should have these documented as well, possibly with a note saying that this is experimental/unstable.
Requiring that all experimental flags be fully documented in the User's Guide is both too onerous for the developer, and too confusing for users, IMO. It's a User's Guide, not a developer's guide, after all! The developer has access to the source code, so they can find out what a flag actually does, and if it's not obvious then a comment should suffice. Cheers, Simon
participants (4)
-
Jan Stolarek -
Johan Tibell -
RodLogic -
Simon Marlow