[Bug driver/92757] New: Documentation ambiguous/misleading about interplay of optimization and warning flags

[ricardolafabreu at gmail dot com]

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

            Bug ID: 92757
           Summary: Documentation ambiguous/misleading about interplay of
                    optimization and warning flags
           Product: gcc
           Version: 8.3.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: driver
          Assignee: unassigned at gcc dot gnu.org
          Reporter: ricardolafabreu at gmail dot com
  Target Milestone: ---

The documentation (man page for gcc 8.3.0 or
https://gcc.gnu.org/onlinedocs/gcc/) could be clearer in what concerns the
interaction of optimization and warnings. That optimization options influence
the correctness analysis (warnings report possible incorrections) is too
general and important a piece of information to be buried in the documentation
of individual warning flags.

The general documentation for those flag classes says things like 

> You can request many specific warnings with options beginning with ‘-W’

or 

> -Wall
> 
>    This enables all the warnings about constructions that some users consider questionable [...]

And the opening message in `--help=warnings` is

> The following options control compiler warning messages: [...]

I find this a bit misleading. There is an ambiguity in that some warnings,
"enabled" via a -Wxyz flag, may be effectively disabled due to optimization
options (or lack thereof). A particular consequence is that -W flags are not
enough to make a build that prints as many warnings as possible (particular -O
flags are needed). 

While the text for the general flag classes claims they enable/control
warnings, it fails to mention that enablement/control is only partial. They
don't *entirely* enable warnings, not always. There is no hint to this in the
general text discussing optimization either, only in particular warning flags.
Without reading the documentation for the right specific warning flag, it is
easy to assume that warning and optimization flags are orthogonal in general. 

To prevent ambiguity from arising in the first place, text claiming general
properties of -W flags could be completed with something like "provided the
required analysis are enabled with the chosen optimization". I believe this
would make the text more accurate and informative. For completeness, the
section on optimization could also say it affects what analysis are done and,
therefore, what warnings are printed.