[PATCH] GCC Warning Options Documentation

["Stephan T. Lavavej" <stl@caltech.edu>]

See the threads beginning at:
http://gcc.gnu.org/ml/gcc/2003-09/msg00598.html
http://gcc.gnu.org/ml/gcc/2003-10/msg00109.html

The patch is at the end of this message.  If E-mail line breaks destroy it
(I'm not sure whether they affect patches), the patch is also available at:
http://stl.nuwen.net/patch.txt

The basic point of the patch is to clean up the -Wall issues, and to a
lesser extent the -Wunused issues.  Feedback would be appreciated; I don't
know if I've missed something or done something wrong.  In particular, while
I know how to bootstrap gcc, I don't know if that generates the
documentation, or how to test that my changes didn't screw anything up.  (I
don't know Texi or whatever this format is.)

I also fixed some other problems:

Removed a stray backslash.

Made a couple of sentences more parallel.

Cleaned up -Wno-long-long.

Added a missing period.

The possessive form of class was improperly written as class'.

Replaced non-null with nonnull because the option is named
-Wnonnull and the GCC Coding Conventions specify that nonzero should be used
in place of non-zero.

This patch does NOT resolve a few issues I noticed earlier.  In particular:

* I would hope that -pedantic doesn't complain about the use of long long in
C99, but the -Wno-long-long entry doesn't say anything about this.

* There are several "(C++ only)" warnings listed on this page. Yet more
appear in the separate page Options Controlling C++ Dialect. Why does
-Wno-invalid-offsetof get to be in Options To Request Or Suppress Warnings
while -Wold-style-cast languishes in Options Controlling C++ Dialect? There
doesn't seem to be any rhyme or reason to this.

* I did not put compound options like -Wall and -Wunused above the things
that they imply. Instead I preserved the current order as much as possible.

Stephan T. Lavavej
http://nuwen.net

Index: gcc/doc/invoke.texi
===================================================================
RCS file: /cvsroot/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.408
diff -a -u -3 -r1.408 invoke.texi
--- gcc/doc/invoke.texi	6 Feb 2004 20:03:45 -0000	1.408
+++ gcc/doc/invoke.texi	16 Feb 2004 02:08:17 -0000
@@ -1264,7 +1264,7 @@
 
 @item -fcheck-new
 @opindex fcheck-new
-Check that the pointer returned by @code{operator new} is non-null
+Check that the pointer returned by @code{operator new} is nonnull
 before attempting to modify the storage allocated.  This check is
 normally unnecessary because the C++ standard specifies that
 @code{operator new} will only return @code{0} if it is declared
@@ -1976,10 +1976,10 @@
 are not inherently erroneous but which are risky or suggest there
 may have been an error.
 
-You can request many specific warnings with options beginning @samp{-W},
-for example @option{-Wimplicit} to request warnings on implicit
+You can request many specific warnings with options beginning with
@samp{-W};
+for example, @option{-Wimplicit} to request warnings on implicit
 declarations.  Each of these specific warning options also has a
-negative form beginning @samp{-Wno-} to turn off warnings;
+negative form beginning with @samp{-Wno-} to turn off warnings;
 for example, @option{-Wno-implicit}.  This manual lists only one of the
 two forms, whichever is not the default.
 
@@ -2039,26 +2039,38 @@
 Like @option{-pedantic}, except that errors are produced rather than
 warnings.
 
+@item -Wno-long-long
+@opindex Wlong-long
+@opindex Wno-long-long
+If @option{-pedantic} is specified, do not warn if the @samp{long long}
type
+is used. @option{-pedantic} implies @option{-Wlong-long} by default. If
+@option{-pedantic} is not specified, @option{-Wlong-long} and
+@option{-Wno-long-long} have no effect.
+
 @item -w
 @opindex w
 Inhibit all warning messages.
 
-@item -Wno-import
+@item -Werror
+@opindex Werror
+Make all warnings into errors.
+
+@item -Wno-import @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wno-import
 Inhibit warning messages about the use of @samp{#import}.
 
-@item -Wchar-subscripts
+@item -Wchar-subscripts @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wchar-subscripts
 Warn if an array subscript has type @code{char}.  This is a common cause
 of error, as programmers often forget that this type is signed on some
 machines.
 
-@item -Wcomment
+@item -Wcomment @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wcomment
 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
 
-@item -Wformat
+@item -Wformat @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wformat
 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
 the arguments supplied have types appropriate to the format string
@@ -2082,11 +2094,10 @@
 Since @option{-Wformat} also checks for null format arguments for
 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
 
-@option{-Wformat} is included in @option{-Wall}.  For more control over
some
-aspects of format checking, the options @option{-Wformat-y2k},
-@option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
-@option{-Wformat-nonliteral}, @option{-Wformat-security}, and
-@option{-Wformat=2} are available, but are not included in @option{-Wall}.
+For more control over some aspects of format checking, the options
+@option{-Wformat-y2k}, @option{-Wno-format-extra-args},
+@option{-Wno-format-zero-length}, @option{-Wformat-nonliteral},
+@option{-Wformat-security}, and @option{-Wformat=2} are available.
 
 @item -Wformat-y2k
 @opindex Wformat-y2k
@@ -2136,15 +2147,12 @@
 @option{-Wformat}.  Currently equivalent to @samp{-Wformat
 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
 
-@item -Wnonnull
+@item -Wnonnull @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wformat}@r{)}
 @opindex Wnonnull
 Warn about passing a null pointer for arguments marked as
-requiring a non-null value by the @code{nonnull} function attribute.
-
-@option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}.  It
-can be disabled with the @option{-Wno-nonnull} option.
+requiring a nonnull value by the @code{nonnull} function attribute.
 
-@item -Winit-self @r{(C, C++, and Objective-C only)}
+@item -Winit-self @r{(C, C++, and Objective-C only)} @r{(Implied by
}@option{-Wall}@r{)}
 @opindex Winit-self
 Warn about uninitialized variables which are initialized with themselves.
 Note this option can only be used with the @option{-Wuninitialized} option,
@@ -2162,28 +2170,28 @@
 @end group
 @end smallexample
 
-@item -Wimplicit-int
+@item -Wimplicit-int @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wimplicit}@r{)}
 @opindex Wimplicit-int
 Warn when a declaration does not specify a type.
 
-@item -Wimplicit-function-declaration
+@item -Wimplicit-function-declaration @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wimplicit}@r{)}
 @itemx -Werror-implicit-function-declaration
 @opindex Wimplicit-function-declaration
 @opindex Werror-implicit-function-declaration
 Give a warning (or error) whenever a function is used before being
 declared.
 
-@item -Wimplicit
+@item -Wimplicit @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wimplicit
 Same as @option{-Wimplicit-int} and
@option{-Wimplicit-function-declaration}.
 
-@item -Wmain
+@item -Wmain @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wmain
 Warn if the type of @samp{main} is suspicious.  @samp{main} should be a
 function with external linkage, returning int, taking either zero
 arguments, two, or three arguments of appropriate types.
 
-@item -Wmissing-braces
+@item -Wmissing-braces @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wmissing-braces
 Warn if an aggregate or union initializer is not fully bracketed.  In
 the following example, the initializer for @samp{a} is not fully
@@ -2194,7 +2202,7 @@
 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
 @end smallexample
 
-@item -Wparentheses
+@item -Wparentheses @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wparentheses
 Warn if parentheses are omitted in certain contexts, such
 as when there is an assignment in a context where a truth value
@@ -2240,7 +2248,7 @@
 @end group
 @end smallexample
 
-@item -Wsequence-point
+@item -Wsequence-point @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wsequence-point
 Warn about code that may have undefined semantics because of violations
 of sequence point rules in the C standard.
@@ -2286,7 +2294,7 @@
 definitions, may be found on our readings page, at
 @w{@uref{http://gcc.gnu.org/readings.html}}.
 
-@item -Wreturn-type
+@item -Wreturn-type @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wreturn-type
 Warn whenever a function is defined with a return-type that defaults to
 @code{int}.  Also warn about any @code{return} statement with no
@@ -2296,7 +2304,7 @@
 message, even when @option{-Wno-return-type} is specified.  The only
 exceptions are @samp{main} and functions defined in system headers.
 
-@item -Wswitch
+@item -Wswitch @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wswitch
 Warn whenever a @code{switch} statement has an index of enumeral type
 and lacks a @code{case} for one or more of the named codes of that
@@ -2304,65 +2312,63 @@
 warning.)  @code{case} labels outside the enumeration range also
 provoke warnings when this option is used.
 
-@item -Wswitch-default
+@item -Wswitch-default @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wswitch-switch
 Warn whenever a @code{switch} statement does not have a @code{default}
 case.
 
-@item -Wswitch-enum
+@item -Wswitch-enum @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wswitch-enum
 Warn whenever a @code{switch} statement has an index of enumeral type
 and lacks a @code{case} for one or more of the named codes of that
 enumeration.  @code{case} labels outside the enumeration range also
 provoke warnings when this option is used.
 
-@item -Wtrigraphs
+@item -Wtrigraphs @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wtrigraphs
 Warn if any trigraphs are encountered that might change the meaning of
 the program (trigraphs within comments are not warned about).
 
-@item -Wunused-function
+@item -Wunused-function @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wunused}@r{)}
 @opindex Wunused-function
 Warn whenever a static function is declared but not defined or a
-non\-inline static function is unused.
+non-inline static function is unused.
 
-@item -Wunused-label
+@item -Wunused-label @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wunused}@r{)}
 @opindex Wunused-label
 Warn whenever a label is declared but not used.
 
 To suppress this warning use the @samp{unused} attribute
 (@pxref{Variable Attributes}).
 
-@item -Wunused-parameter
+@item -Wunused-parameter @r{(Implied by }@samp{-Wall -Wextra}@r{ or
}@samp{-Wunused -Wextra}@r{)}
 @opindex Wunused-parameter
 Warn whenever a function parameter is unused aside from its declaration.
 
 To suppress this warning use the @samp{unused} attribute
 (@pxref{Variable Attributes}).
 
-@item -Wunused-variable
+@item -Wunused-variable @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wunused}@r{)}
 @opindex Wunused-variable
 Warn whenever a local variable or non-constant static variable is unused
-aside from its declaration
+aside from its declaration.
 
 To suppress this warning use the @samp{unused} attribute
 (@pxref{Variable Attributes}).
 
-@item -Wunused-value
+@item -Wunused-value @r{(Implied by }@option{-Wall}@r{ or
}@option{-Wunused}@r{)}
 @opindex Wunused-value
 Warn whenever a statement computes a result that is explicitly not used.
 
 To suppress this warning cast the expression to @samp{void}.
 
-@item -Wunused
+@item -Wunused @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wunused
-All the above @option{-Wunused} options combined.
+All options beginning with @samp{-Wunused} combined with the exception of
+@option{-Wunused-parameter}, which is implied by @option{-Wunused} when
used
+in conjunction with @option{-Wextra}.
 
-In order to get a warning about an unused function parameter, you must
-either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
-@samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
-
-@item -Wuninitialized
+@item -Wuninitialized @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wuninitialized
 Warn if an automatic variable is used without first being initialized or
 if a variable may be clobbered by a @code{setjmp} call.
@@ -2440,7 +2446,7 @@
 you use that never return as @code{noreturn}.  @xref{Function
 Attributes}.
 
-@item -Wunknown-pragmas
+@item -Wunknown-pragmas @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wunknown-pragmas
 @cindex warning for unknown pragmas
 @cindex unknown pragmas, warning
@@ -2450,32 +2456,30 @@
 for unknown pragmas in system header files.  This is not the case if
 the warnings were only enabled by the @option{-Wall} command line option.
 
-@item -Wstrict-aliasing
+@item -Wstrict-aliasing @r{(Implied by }@option{-Wall}@r{)}
 @opindex Wstrict-aliasing
 This option is only active when @option{-fstrict-aliasing} is active.
 It warns about code which might break the strict aliasing rules that the
 compiler is using for optimization. The warning does not catch all
-cases, but does attempt to catch the more common pitfalls. It is
-included in @option{-Wall}.
+cases, but does attempt to catch the more common pitfalls.
 
 @item -Wall
 @opindex Wall
-All of the above @samp{-W} options combined.  This enables all the
-warnings about constructions that some users consider questionable, and
-that are easy to avoid (or modify to prevent the warning), even in
-conjunction with macros.  This also enables some language-specific
+This implies many individual options. Whether an individual option is
implied
+by @option{-Wall} is noted before the description of the individual option.
+This enables all the warnings about constructions that some users consider
+questionable, and that are easy to avoid (or modify to prevent the
warning),
+even in conjunction with macros.  This also enables some language-specific
 warnings described in @ref{C++ Dialect Options} and
 @ref{Objective-C Dialect Options}.
-@end table
+@option{-Wall} represents a consensus about which warning options should be
+recommended in all situations. Individual options which are not implied by
+@option{-Wall} can be useful in specific situations. Some of them warn
about
+constructions that users generally do not consider questionable, but which
+occasionally they might wish to check for; others warn about constructions
+that are necessary or hard to avoid in some cases, and there is no simple
+way to modify the code to suppress the warning.
 
-The following @option{-W@dots{}} options are not implied by @option{-Wall}.
-Some of them warn about constructions that users generally do not
-consider questionable, but which occasionally you might wish to check
-for; others warn about constructions that are necessary or hard to avoid
-in some cases, and there is no simple way to modify the code to suppress
-the warning.
-
-@table @gcctabopt
 @item -Wextra
 @opindex W
 @opindex Wextra
@@ -2584,7 +2588,7 @@
 Taking the address of a variable which has been declared @samp{register}.
 
 @item @r{(C++ only)}
-A base class is not initialized in a derived class' copy constructor.
+A base class is not initialized in a derived class's copy constructor.
 @end itemize
 
 @item -Wno-div-by-zero
@@ -2955,14 +2959,6 @@
 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
 the search path but can't be used.
 
-@item -Wlong-long
-@opindex Wlong-long
-@opindex Wno-long-long
-Warn if @samp{long long} type is used.  This is default.  To inhibit
-the warning messages, use @option{-Wno-long-long}.  Flags
-@option{-Wlong-long} and @option{-Wno-long-long} are taken into account
-only when @option{-pedantic} flag is used.
-
 @item -Wdisabled-optimization
 @opindex Wdisabled-optimization
 Warn if a requested optimization pass is disabled.  This warning does
@@ -2971,10 +2967,6 @@
 effectively.  Often, the problem is that your code is too big or too
 complex; GCC will refuse to optimize programs when the optimization
 itself is likely to take inordinate amounts of time.
-
-@item -Werror
-@opindex Werror
-Make all warnings into errors.
 @end table
 
 @node Debugging Options