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?
commit a923e297acfd7c0ca3d3820463450f38230ab4ea Author: Jonathan Wakely <jwak...@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}.