[PATCH] Improve -Wmaybe-uninitialized documentation

[Jonathan Wakely]

The docs for -Wmaybe-uninitialized have some issues:

- That first sentence is looooooong.
- Apparently some C++ programmers think "automatic variable" means one
  declared with C++11 `auto`, rather than simply a local variable.
- The sentence about only warning when optimizing is stuck in between
  two chunks talking about longjmp, which could be inferred to mean
  only the setjmp/longjmp part of the warning depends on optimization.

This attempts to make it easier to parse and understand.

OK for trunk?

-------------- next part --------------
commit a923e297acfd7c0ca3d3820463450f38230ab4ea
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Wed Nov 15 14:25:09 2017 +0000

    Improve -Wmaybe-uninitialized documentation
    
            * doc/invoke.texi (-Wmaybe-uninitialized): Rephrase more accurately.

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 44273284483..fac4122fe3e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -4970,14 +4970,17 @@ void store (int *i)
 @item -Wmaybe-uninitialized
 @opindex Wmaybe-uninitialized
 @opindex Wno-maybe-uninitialized
-For an automatic variable, if there exists a path from the function
-entry to a use of the variable that is initialized, but there exist
-some other paths for which the variable is not initialized, the compiler
-emits a warning if it cannot prove the uninitialized paths are not
-executed at run time. These warnings are made optional because GCC is
-not smart enough to see all the reasons why the code might be correct
-in spite of appearing to have an error.  Here is one example of how
-this can happen:
+Warn if there exists a path from entry to a function to a use of an automatic
+(i.e.@ local) variable, for which the variable is not initialized, and the
+compiler cannot prove that the uninitialized path will not be executed at run
+time.
+
+These warnings are only possible in optimizing compilation, because otherwise
+GCC does not keep track of the state of variables.
+
+These warnings are optional because GCC is not smart enough to see all the
+reasons why the code might be correct in spite of appearing to have an error.
+Here is one example of how this can happen:
 
 @smallexample
 @group
@@ -5003,19 +5006,15 @@ warning, you need to provide a default case with assert(0) or
 similar code.
 
 @cindex @code{longjmp} warnings
-This option also warns when a non-volatile automatic variable might be
-changed by a call to @code{longjmp}.  These warnings as well are possible
-only in optimizing compilation.
-
-The compiler sees only the calls to @code{setjmp}.  It cannot know
-where @code{longjmp} will be called; in fact, a signal handler could
-call it at any point in the code.  As a result, you may get a warning
-even when there is in fact no problem because @code{longjmp} cannot
-in fact be called at the place that would cause a problem.
+This option also warns when a non-volatile automatic variable might be changed
+by a call to @code{longjmp}.  The compiler sees only the calls to
+@code{setjmp}.  It cannot know where @code{longjmp} will be called; in fact, a
+signal handler could call it at any point in the code.  As a result, you may
+get a warning even when there is in fact no problem because @code{longjmp}
+cannot in fact be called at the place that would cause a problem.
 
 Some spurious warnings can be avoided if you declare all the functions
-you use that never return as @code{noreturn}.  @xref{Function
-Attributes}.
+you use that never return as @code{noreturn}.  @xref{Function Attributes}.
 
 This warning is enabled by @option{-Wall} or @option{-Wextra}.