The -Warray-bounds description in the manual is out of date in
a couple of ways. First it claims that the option is only active
with optimization, which isn't entirely correct since at least one
instance is issued even without it. Second, the description of
its level 2 suggests it controls the warning for all trailing
array members, when it only controls it for trailing one-element
arrays (this was made tighter in GCC 10 but we neglected to update
the manual).
In addition, the word "always" in the description of the option
is also interpreted by some as implying that every instance of
the warning is necessarily a true positive. I've reworded
the description to hopefully avoid this misreading(*).
Finally, the generic text that talks about the interaction with
optimizations says that -Wmaybe-uninitialized is not issued unless
optimization is enabled. That's also not accurate anymore since
at least one instance of the warning is independent of optimization
(passing uninitialized objects by reference to const arguments).
The attached changes correct these oversights.
Martin
[*] It should probably be made clearer in the generic text that
no instance of any warning, not just -Warray-bounds, should be
taken to be a definitive indication of a bug in the code. I've
left that for later.
Update -Warray-bounds documentation [PR104355].
Resolves:
PR middle-end/104355 - Misleading and outdated -Warray-bounds documentation
gcc/ChangeLog:
* doc/invoke.texi (-Warray-bounds): Update documentation.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index b49ba22df89..b7b1f47a5ce 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -5641,8 +5641,10 @@ warns that an unrecognized option is present.
The effectiveness of some warnings depends on optimizations also being
enabled. For example @option{-Wsuggest-final-types} is more effective
-with link-time optimization and @option{-Wmaybe-uninitialized} does not
-warn at all unless optimization is enabled.
+with link-time optimization and some instances of other warnings may
+not be issued at all unless optimization is enabled. While optimization
+in general improves the efficacy of control and data flow sensitive
+warnings, in some cases it may also cause false positives.
@table @gcctabopt
@item -Wpedantic
@@ -7691,20 +7693,22 @@ void f (char c, int i)
@itemx -Warray-bounds=@var{n}
@opindex Wno-array-bounds
@opindex Warray-bounds
-This option is only active when @option{-ftree-vrp} is active
-(default for @option{-O2} and above). It warns about subscripts to arrays
-that are always out of bounds. This warning is enabled by @option{-Wall}.
+Warn about out of bounds subscripts or offsets into arrays. This warning
+level is enabled by @option{-Wall}. It is the most effective when
+@option{-ftree-vrp} is active (the default for @option{-O2} and above)
+but a subset of instances are issued even without optimization.
@table @gcctabopt
@item -Warray-bounds=1
-This is the warning level of @option{-Warray-bounds} and is enabled
+This is the default warning level of @option{-Warray-bounds} and is enabled
by @option{-Wall}; higher levels are not, and must be explicitly requested.
@item -Warray-bounds=2
-This warning level also warns about out of bounds access for
-arrays at the end of a struct and for arrays accessed through
-pointers. This warning level may give a larger number of
-false positives and is deactivated by default.
+This warning level also warns out of bounds accesses to trailing struct
+members of one-element array types (@pxref{Zero Length}) and about
+the intermediate results of pointer arithmetic that may yield out of
+bounds values. This warning level may give a larger number of false
+positives and is deactivated by default.
@end table
@item -Warray-compare
