Document the 'manywarnings' module.

diff --git a/ChangeLog b/ChangeLog
index 7b2fe13986ac7184205bfa35c4682c25ff808bdb..d34dbab54d1b79cc4dcda14033cfb7f5ea85de85 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2008-12-06  Bruno Haible  <bruno@clisp.org>
+
+       Document the 'manywarnings' module.
+       * doc/manywarnings.texi: New file.
+       * doc/gnulib.texi: Include it.
+
 2008-12-05  Eric Blake  <ebb9@byu.net>
 
        tests: silence some gcc warnings

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index fa0d156f1367a47277a3173235201ed0203bafd5..a93b64345e888322c13f4d2d5abd50b4f6096e44 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -5757,6 +5757,7 @@ This list of functions is sorted according to the header that declares them.
 * Supporting Relocation::
 * func::
 * warnings::
+* manywarnings::
 @end menu
 
 @node alloca
@@ -5840,6 +5841,8 @@ generated automatically.
 
 @include warnings.texi
 
+@include manywarnings.texi
+
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License

diff --git a/doc/manywarnings.texi b/doc/manywarnings.texi
new file mode 100644 (file)
index 0000000..2ad807e
--- /dev/null
+++ b/doc/manywarnings.texi
@@ -0,0 +1,48 @@
+@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 warning that weren't already triggered by the existing code
+base.
+
+An example use of the module is as follows:
+
+@smallexample
+gl_MANYWARN_ALL_GCC([warnings])
+# Set up the list of the pointless, undesired warnings.
+nw=
+nw="$nw -Wsystem-headers"       # Don't let system headers trigger warnings
+nw="$nw -Wundef"                # All compiler preprocessors support #if UNDEF
+nw="$nw -Wtraditional"          # All compilers nowadays support ANSI C
+nw="$nw -Wconversion"           # These warnings usually don't point to mistakes.
+nw="$nw -Wsign-conversion"      # Likewise.
+# Enable all GCC warnings not in this list.
+gl_MANYWARN_COMPLEMENT[warnings], [$warnings], [$nw])
+for w in $warnings; do
+  gl_WARN_ADD([$w])
+done
+@end smallexample
+
+This module is meant to be used by developers who are not very experienced
+regarding the various GCC warning option. In the beginning you will 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 is originated from which option. 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.
+
+There are also many GCC warning options which 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
+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
+new warnings, while adding the undesired ones to the @samp{nw} variable.