ANN: Updating flag description in the User's Guide

[RodLogic]

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:
>
>> 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 at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-devs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/ghc-devs/attachments/20141106/d353ef2a/attachment.html>