ANN: Updating flag description in the User's Guide
dev at rodlogic.net
Thu Nov 6 12:48:51 UTC 2014
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 <marlowsd at gmail.com> wrote:
> On 06/11/2014 12:06, Jan Stolarek wrote:
>> I have some important information for everyone.
>> TL;DR1 As a rule of thumb, whenever you modify DynFlags or StaticFlags
>> 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
>> (#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
>> labeled as static, etc. It seems that we don't have a habit of updating
>> 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
>> 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
>> 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 .
> Your efforts are much appreciated, thankyou :)
> These flags are currently completely missing from the User's Guide:
> 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
>> This seems to go against our convention of describing the flags. Should we
>> revert to desribing their normal version (ie. ones that enable something,
> 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
> isn't -ddump-simpl-phases useful? what's the other way to do that?
> ghc-devs mailing list
> ghc-devs at haskell.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the ghc-devs