[gcc r12-7234] Update -Warray-bounds documentation [PR104355].

[gcc r12-7234] Update -Warray-bounds documentation [PR104355].

[Martin Sebor]

https://gcc.gnu.org/g:7a1b179b08bc802280ca90ed4c6c8d8b25503e66

commit r12-7234-g7a1b179b08bc802280ca90ed4c6c8d8b25503e66
Author: Martin Sebor <msebor@redhat.com>
Date:   Mon Feb 14 15:40:25 2022 -0700

    Update -Warray-bounds documentation [PR104355].
    
    Resolves:
    PR middle-end/104355 - Misleading and outdated -Warray-bounds documentation
    
    gcc/ChangeLog:
            PR middle-end/104355
            * doc/invoke.texi (-Warray-bounds): Update documentation.

Diff:
---
 gcc/doc/invoke.texi | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index b49ba22df89..e1a00c80307 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
+is enabled by @option{-Wall}.  It is more 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 about 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