[Bug driver/41179] Documentation for "-fno-toplevel-reorder" is confusing (and wrong)

[msebor at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=41179

Martin Sebor <msebor at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |documentation
             Status|UNCONFIRMED                 |NEW
   Last reconfirmed|                            |2017-02-07
                 CC|                            |msebor at gcc dot gnu.org
     Ever confirmed|0                           |1

--- Comment #2 from Martin Sebor <msebor at gcc dot gnu.org> ---
The description of the option has changed since this issue was first raised but
I agree that the description could be made clearer.  In GCC 7 it reads:

  -fno-toplevel-reorder
       Do not reorder top-level functions, variables, and asm statements.
Output them in the same order that they appear in the input file. When this
option is used, unreferenced static variables are not removed. This option is
intended to support existing code that relies on a particular ordering. For new
code, it is better to use attributes when possible.

       Enabled at level -O0. When disabled explicitly, it also implies
-fno-section-anchors, which is otherwise enabled at -O0 on some targets.

The confusing "-fno-xxx" option ... is enabled/disabled" phrasing is used in at
least a couple pf others places:

  -fno-defer-pop
       ...
       Disabled at levels -O, -O2, -O3, -Os. 

It's unclear whether disabled means -fno-defer-pop is in effect, or whether it
means that -fdefer-pop is.

Or, arguably even more confusing:

  -fno-branch-count-reg
  ...
       Enabled by default at -O1 and higher.
       The default is -fbranch-count-reg.

Most of the remaining -fno-xxx (and -fxxx) options use the phrase "The default
is -fxxx" (or "The default is -fno-xxx"), such as "The default is
-fzero-initialized-in-bss."  I think it would be best to adopt this style
throughout.