On 10/3/19 9:16 AM, Bernd Edlinger wrote:
Hi,
I've noticed that the documentation of -Wshadow=x has some
missing bits, and I want to add an negative example to
-Wshadow=compatble-local.
Bootstrapped and reg-tested on x86_64-pc-linux-gnu.
Is it OK for trunk?
Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi (revision 276484)
+++ gcc/doc/invoke.texi (working copy)
@@ -6477,13 +6477,14 @@ Do not warn whenever a local variable shadows an i
Objective-C method.
@item -Wshadow=global
-@opindex Wshadow=local
+@opindex Wshadow=global
The default for @option{-Wshadow}. Warns for any (global) shadowing.
+This warning is enabled by @option{-Wshadow=global}.
This is redundant and adds nothing to the description except to make it
more verbose.
@item -Wshadow=local
@opindex Wshadow=local
Warn when a local variable shadows another local variable or parameter.
-This warning is enabled by @option{-Wshadow=global}.
+This warning is enabled by @option{-Wshadow=local}.
I think this incorrectly changes the meaning. What the existing
documentation is saying is that -Wshadow=global *also* enables warnings
about local variables as if -Wshadow=local were specified explicitly.
If the code itself has changed so that -Wshadow=global no longer implies
-Wshadow=local, then the added sentence is simply redundant as above.
@item -Wshadow=compatible-local
@opindex Wshadow=compatible-local
@@ -6515,8 +6516,10 @@ in place of the other, type checking will catch th
warning. So not warning (about shadowing) in this case will not lead to
undetected bugs. Use of this flag instead of @option{-Wshadow=local} can
possibly reduce the number of warnings triggered by intentional shadowing.
+Note that this does also mean that shadowing @code{const char *i} by
+@code{char *i} will not emit a warning.
-This warning is enabled by @option{-Wshadow=local}.
+This warning is enabled by @option{-Wshadow=compatible-local}.
Similar issues here; the existing docs are saying -Wshadow=local implies
-Wshadow=compatible-local.
@item -Wlarger-than=@var{byte-size}
@opindex Wlarger-than=
If you want to try again to fix the documentation, please also fix this
-Wshadow=global, -Wshadow=local, -Wshadow=compatible-local @gol
in the "Option Summary" (we don't use commas as delimiters in these
tables) and please try to rewrite the paragraph discussing the existing
-Wshadow=compatible-local example to s/variable/variables/ and use the
present tense instead of the future:
Since the two variable @code{i} in the example above have incompatible
types,
enabling only @option{-Wshadow=compatible-local} will not emit a warning.
Because their types are incompatible, if a programmer accidentally uses one
in place of the other, type checking will catch that and emit an error or
warning. So not warning (about shadowing) in this case will not lead to
undetected bugs. Use of this flag instead of @option{-Wshadow=local} can
possibly reduce the number of warnings triggered by intentional shadowing.
-Sandra
