manywarnings: bring doc up to date

* doc/manywarnings.texi: Bring doc up to date for GCC 12.

2 files changed, 63 insertions, 27 deletions

diff --git a/ChangeLog b/ChangeLog
index 9ae7506f45..5246e88037 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,8 @@
 2023-04-23  Paul Eggert  <eggert@cs.ucla.edu>
 
+	manywarnings: bring doc up to date
+	* doc/manywarnings.texi: Bring doc up to date for GCC 12.
+
 	manywarnings: omit -fno-common in GCC 10+
 	* m4/manywarnings.m4 (gl_MANYWARN_ALL_GCC): Omit -fno-common
 	in GCC 10 and later, as it is the default there.
diff --git a/doc/manywarnings.texi b/doc/manywarnings.texi
index 7ab3f09cee..32237dc67f 100644
--- a/doc/manywarnings.texi
+++ b/doc/manywarnings.texi
@@ -1,57 +1,90 @@
 @node manywarnings
 @section manywarnings
 
-The @code{manywarnings} module allows you to enable as many GCC warnings as
-possible for your package. The purpose is to protect against introducing new
-code that triggers warnings that weren't already triggered by the existing code
-base.
-
-An example use of the module is as follows:
+The @code{manywarnings} module enables many GCC warnings for your
+package.  Here is an example use:
 
 @smallexample
-gl_MANYWARN_ALL_GCC([warnings])
-# Set up the list of the pointless, undesired warnings.
-nw=
-nw="$nw -Winline"           # It's OK to not inline.
-nw="$nw -Wstrict-overflow"  # It's OK to optimize strictly.
-nw="$nw -Wsystem-headers"   # Don't let system headers trigger warnings.
-# Enable all GCC warnings not in this list.
-gl_MANYWARN_COMPLEMENT([warnings], [$warnings], [$nw])
-for w in $warnings; do
-  gl_WARN_ADD([$w])
-done
+AC_ARG_ENABLE([gcc-warnings],
+  [AS_HELP_STRING([--enable-gcc-warnings@@<:@@=TYPE@@:>@@],
+    [control generation of GCC warnings.  The TYPE 'no' disables
+     warnings; 'yes' (default) generates cheap warnings;
+     'expensive' in addition generates expensive warnings.])])
+
+AS_IF([test "$enable_gcc_warnings" != no],
+  [gl_MANYWARN_ALL_GCC([warnings])
+
+   # Set up the list of unwanted warning options.
+   nw=
+   if test "$enable_gcc_warnings" != expensive; then
+     nw="$nw -fanalyzer"
+   fi
+   nw="$nw -Winline"           # It's OK to not inline.
+   nw="$nw -Wstrict-overflow"  # It's OK to optimize strictly.
+   nw="$nw -Wsystem-headers"   # Don't warn in system headers.
+
+   # Enable all GCC warnings not in this list.
+   gl_MANYWARN_COMPLEMENT([warnings], [$warnings], [$nw])
+   for w in $warnings; do
+     gl_WARN_ADD([$w])
+   done
+
+   # Disable unwanted warnings enabled by default, -Wall, -Wextra.
+   gl_WARN_ADD([-Wno-sign-compare]) # Too many false alarms.
+])
 @end smallexample
 
-This module is meant to be used by developers who are not very experienced
-regarding the various GCC warning options. In the beginning you will set the
+This module sets up many GCC warning options.
+When you start to use it, you can set the
 list of undesired warnings (@samp{nw} in the example above) to empty, and
-compile the package with all possible warnings enabled. The GCC option
-@code{-fdiagnostics-show-option}, available in GCC 4.1 or newer, helps
-understanding which warnings originated from which option. Then you will
+compile the package with all possible warnings enabled.  Then you will
 go through the list of warnings. You will likely deactivate warnings that
 occur often and don't point to mistakes in the code, by adding them to the
 @samp{nw} variable, then reconfiguring and recompiling. When warnings point
 to real mistakes and bugs in the code, you will of course not disable
 them but fix your code to silence the warning instead.
 
-There are also many GCC warning options which usually don't point to mistakes
+Many GCC warning options usually don't point to mistakes
 in the code; these warnings enforce a certain programming style. It is a
 project management decision whether you want your code to follow any of these
 styles. Note that some of these programming styles are conflicting. You
 cannot have them all; you have to choose among them.
 
-When a new version of GCC is released, you can add the new warning options
+When a new version of GCC is released, you can add the warning options
 that it introduces into the @code{gl_MANYWARN_ALL_GCC} macro (and submit your
-modification to the Gnulib maintainers :-)), and enjoy the benefits of the
+modification to the Gnulib maintainers), and enjoy the benefits of the
 new warnings, while adding the undesired ones to the @samp{nw} variable.
 
 Comments on particular warning flags:
 
 @table @samp
 
+@item -fanalyzer
+The @code{manywarnings} module by default uses GCC's
+@option{-fanalyzer} option, as this issues some useful warnings.
+(It can also help GCC generate better code.)
+However, @code{-fanalyzer} can greatly slow down compilation,
+and in programs with large modules it can be so slow as to be unusable,
+so it is common for @command{configure} to disable it unless
+@command{configure} is given an option like
+@option{--enable-gcc-warnings=expensive}.
+
+@item -fstrict-aliasing
+Although the @code{manywarnings} module does not enable GCC's
+@option{-fstrict-aliasing} option, it is enabled by default if you
+compile with @code{-O2} or higher optimization, and can help GCC
+generate better warnings.
+
+@item -Wanalyzer-malloc-leak
+The @code{-fanalyzer} option generates many false alarms about
+@code{malloc} leaks, which @code{manywarnings} suppresses by also
+using @option{-Wno-analyzer-malloc-leak}.
+
 @item -Wsign-compare
-Clang generates too many false alarms with -Wsign-compare, and we don't
-recommend that warning.  Programs using Gnulib generally don't enable
+GCC and Clang generate too many false alarms with @option{-Wsign-compare},
+and we don't recommend that warning.  You can disable it by using
+@code{gl_WARN_ADD([-Wno-sign-compare])} as illustrated above.
+Programs using Gnulib generally don't enable
 that warning when compiling Gnulib code.  If you happen to find a real
 bug with that warning we'd like to know it.