Lots of suggestions for the gcc manual

Lots of suggestions for the gcc manual

[Stephan Thomas Lavavej]

http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#Warning%20Options

1. Currently, it is very unclear which warnings are part of -Wall
and which are not. In the middle of the page:

> -Wall
> All of the above -W options combined.
> [...]
> The following -W... options are not implied by -Wall.

That would be nice if only it were true. Above -Wall we see:

> -Wformat
> Check calls to printf and scanf
> [...]
> -Wformat is included in -Wall. For more control over some aspects of
> format checking, the options -Wno-format-y2k, -Wno-format-extra-args,
> -Wno-format-zero-length, -Wformat-nonliteral, -Wformat-security, and
> -Wformat=2 are available, but are not included in -Wall.

> -Wno-format-y2k [...]

This is a -W option that appears above -Wall but is not included in -Wall.
Uh oh. Maybe it counts as a -Wno option and so obviously wouldn't be
included in -Wall.

Well, the wording, namely:

> If -Wformat is specified, do not warn about strftime formats which may
> yield only a two-digit year.

makes it pretty clear that it's used on top of -Wformat in order to
*disable* some of -Wformat's functionality. I guess it makes sense, though
the presentation could stand to be a bit clearer. It gets worse, though:

> -Wformat-nonliteral
> If -Wformat is specified, also warn if the format string is
> not a string literal [...]

This is a -W option that turns on more warnings, and appears above -Wall
but is not part of -Wall.

Confusing! It's a mess.

2.
> -Wnonnull is included in -Wall and -Wformat.
> It can be disabled with the -Wno-nonnull option.

The second sentence here is redundant - it already says at the top of the
page how any option can be toggled.

I propose a clearer layout would be to begin the document with
-fsyntax-only, -pedantic, -pedantic-errors, and -w as it currently
does, and then to begin a whole new section: Warnings Included In -Wall.
Every warning that -Wall enables would go in that section and nothing
else. If a warning can be further modified, as -Wformat can be, then
it should link to /another/ section that explains all the modifications
that can be done, but under no circumstances should any warnings not
in -Wall appear in the -Wall section.

3.
> -Winit-self (C, C++, and Objective-C only)
> Enable warning about

The rest of the options say "warn if", "warn whenever", etc. "Warn about"
would fit perfectly here and be shorter as well as more consistent.

> uninitialized variables which are
> initalized

Misspelled.

> Note this option can only be used with the -Wuninitialized option and
> that only works with -O.

Does it work with -O2, etc?

> For an example,

Would "For example" be better?

> the following code will not warn about i

Elsewhere, variables that appear in the main text are in monospace.
This occurrence of i is not.

In fact, the whole sentence

> the following code will not warn about i being uninitialized
> without this option

is pretty icky. Does code warn, or does gcc warn? And the sentence
uses a confusing double negative.

4.
> -Wstrict-aliasing
[...]
> It is included in -Wall.

The reorganization I suggest in (2) would make this sentence redundant.

5. Shouldn't -Wlong-long appear next to -pedantic?

6. 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.

Stephan T. Lavavej
http://stl.caltech.edu

Re: Lots of suggestions for the gcc manual

[Kai Henningsen]

stl@caltech.edu (Stephan Thomas Lavavej)  wrote on 13.09.03 in <Pine.GSO.4.58.0309130347490.24873@blinky>:

> I propose a clearer layout would be to begin the document with
> -fsyntax-only, -pedantic, -pedantic-errors, and -w as it currently
> does, and then to begin a whole new section: Warnings Included In -Wall.
> Every warning that -Wall enables would go in that section and nothing
> else. If a warning can be further modified, as -Wformat can be, then
> it should link to /another/ section that explains all the modifications
> that can be done, but under no circumstances should any warnings not
> in -Wall appear in the -Wall section.

I have an alternate proposal: every warning that is in -Wall should be  
listed as

`-Wformat' (in -Wall)

and similar for -Wextra.

Oh, and for always-on-but-can-be-disabled there should be a similar remark  
right after the option name, possibly "(default on)". Similar "(C++ only)"  
and whatever else seems appropriate.

Apart from that, I'd like these to be sorted strictly alphabetically.

Another thing that would be very good would be to include the exact  
warning text(s) triggered by the warnings; this would make it much easier  
to find the relevant option when you have a message (and that option is,  
after all, the only place you are likely to find any kind of explanation).

MfG Kai

Re: Lots of suggestions for the gcc manual

[Gerald Pfeifer]

On Sun, 14 Sep 2003, Kai Henningsen wrote:
> I have an alternate proposal: every warning that is in -Wall should be
> listed as
>
> `-Wformat' (in -Wall)
>
> and similar for -Wextra.

I think that's a useful idea.  Neil, Joseph, what do you think?

> Apart from that, I'd like these to be sorted strictly alphabetically.

I don't feel strongly either way, but indeed this would get rid of some
of the problems Stephan noticed.


In the next one or two days I'll try to cook up a patch for (most of)
Stephan's comments.  Unless there are strong (and well-argued) objections
to such a change, I think I'll happily accept a patch making the two
changes you suggest above!

Gerald
-- 
Gerald Pfeifer (Jerry)   gerald@pfeifer.com   http://www.pfeifer.com/gerald/

PATCH for: Lots of suggestions for the gcc manual

[Gerald Pfeifer]

On Sat, 13 Sep 2003, Stephan Thomas Lavavej wrote:
> http://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#Warning%20Options

What do you think about the following patch to address several specific
observations you made?

(Concerning your general remarks on how to restructure the list of
options, I'd slightly prefer the variant someone else suggested in
a followup.  For that, however, I'm afraid we'd need to a volunteer
to summarize the suggested changes to the gcc list and, once consensus
has been reached, provide a patch.  I'd really appreciate that.)

Gerald

2003-10-03  Gerald Pfeifer  <gerald@pfeifer.com>

	* doc/invoke.texi (Warning Options): Simplify and clarify the
	descriptions of -Wnonnull and -Winit-self.

Index: doc/invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.339
diff -u -3 -p -r1.339 invoke.texi
--- doc/invoke.texi	25 Sep 2003 01:25:52 -0000	1.339
+++ doc/invoke.texi	3 Oct 2003 18:50:38 -0000
@@ -2172,7 +2172,7 @@ Enable @option{-Wformat} plus format che

 @item -Wnonnull
 @opindex Wnonnull
-Enable warning about passing a null pointer for arguments marked as
+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
@@ -2180,12 +2180,12 @@ can be disabled with the @option{-Wno-no

 @item -Winit-self @r{(C, C++, and Objective-C only)}
 @opindex Winit-self
-Enable warning about uninitialized variables which are initalized with themselves.
-Note this option can only be used with the @option{-Wuninitialized} option and
-that only works with @option{-O}.
+Warn about uninitialized variables which are initialized with themselves.
+Note this option can only be used with the @option{-Wuninitialized} option,
+which in turn only works with @option{-O1} and above.

-For an example, the following code will not warn about i being uninitialized
-without this option:
+For example, GCC will warn about @code{i} being uninitialized in the
+following snippet only when @option{-Winit-self} has been specified:
 @smallexample
 @group
 int f()

RE: PATCH for: Lots of suggestions for the gcc manual

[Stephan T. Lavavej]

[Gerald Pfeifer]
> What do you think about the following patch to address several specific
> observations you made?

Let's see...

>  @item -Wnonnull
>  @opindex Wnonnull
> -Enable warning about passing a null pointer for arguments marked as
> +Warn about passing a null pointer for arguments marked as

Hey, I missed this instance of "enable warning about"!  Good catch.

The rest of the changes fix up -Winit-self nicely.  The patch is fine with
me.

-----

Other things I've noticed:

> You can request many specific warnings with options beginning -W, for
> example -Wimplicit to request warnings on implicit declarations. Each of
> these specific warning options also has a negative form beginning -Wno- to
> turn off warnings; for example, -Wno-implicit.

These sentences should be parallel.  "with" should be added to each
sentence: "beginning with -W" and "beginning with -Wno-".  The first
sentence should use a semicolon rather than a comma, to match the second:
"-W; for example".  A comma should appear after "for example" in the first
sentence to match the second.

> -Wunused-function 
> Warn whenever a static function is declared but not defined or a
> non\-inline static function is unused. 

What is the backslash doing there?

-----

> (Concerning your general remarks on how to restructure the list of
> options, I'd slightly prefer the variant someone else suggested in
> a followup.  For that, however, I'm afraid we'd need to a volunteer
> to summarize the suggested changes to the gcc list and, once consensus
> has been reached, provide a patch.  I'd really appreciate that.)

Okay, here are my suggestions:

1. Begin with -fsyntax-only, -pedantic, and -pedantic-errors as we do now.
(Isn't -pedantic-errors redundant?  Shouldn't -pedantic -Werror do the same
thing?)

2. Move -Wlong-long right after -pedantic-errors.  It currently says:

-Wlong-long 
Warn if long long type is used. This is default. To inhibit the warning
messages, use -Wno-long-long. Flags -Wlong-long and -Wno-long-long are taken
into account only when -pedantic flag is used.

Now, at the beginning of the section, the manual makes a big deal about how
it (supposedly) only lists the non-default version.  We may as well follow
this here.  So, I suggest that this be used:

-Wno-long-long
If -pedantic is specified, do not warn if long long type is used.  -pedantic
implies -Wlong-long by default.  If -pedantic is not specified, -Wlong-long
and -Wno-long-long have no effect.

Also, this should probably say something about C99; I would hope that
-pedantic doesn't complain about the use of long long in C99.

3. -w should come next as it currently does.

3.5. (Didn't want to renumber.)  Then -Werror should come next.  If turning
off all warnings belongs at the top, so does making all warnings into hard
errors.

4. -Wextra should come next.  I believe that -Wextra should not come between
-Wall and the things that -Wall turns on, so it should either appear before
-Wall entirely or after all the things that -Wall turns on.  The latter
would put it near the end of the document and still might give the
impression that it is part of -Wall.  (-Wall needs a name change...  I
jokingly suggest -Wmost.)

5. -Wall should come next.  It currently says:

-Wall 
All of the above -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 warnings described in C++ Dialect
Options and Objective-C Dialect Options. 
The following -W... options are not implied by -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.

I suggest:

-Wall
Implies the following options:
[ginormous list of options follows]
Also implies some language-specific warnings described in C++ Dialect
Options and Objective-C Dialect Options:
[somewhat less ginormous list of options follows]
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. 
Some of the options not implied by -Wall 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.

I might also suggest changing "you might wish" to "they might wish"; "users"
is sitting right before that, and the change is a bit disharmonious.

6. Each option included in -Wall should say (in -Wall).

7. -Wall should be followed by the options that it turns on.  This need not
be a contiguous block, since (1) -Wall won't say "all of the previous
options combined" anymore, and (2) each option included in -Wall says so.
Still, grouping them rather tightly is the clearest way to go about things.

8. -Wformat needs significant cleanups.  I suggest that it be organized like
-Wall.  So, -Wformat would list all the things it turns on, and then there
would be individual breakdowns of the things it turns on.  This would be
preferable to listing -Wformat and then listing things which turn off parts
of -Wformat.  -Wformat should say (in -Wall) and things in -Wformat like
-Wformat-y2k should say (in -Wall and -Wformat).

9. -Wimplicit is another option like -Wall, even though it only has two
things in it.

10. -Wunused is yet another option like -Wall.  (It's all this nesting and
chains of implications that makes the current organization so unwieldy.) 

11. After (in -Wall) has been added to the appropriate functions, their
descriptions should be grepped to make sure they don't mention that they're
included in -Wall.

12. The list of options that -Wall implies, and the functions which claim to
be part of -Wall should be checked for consistency, and they shouldn't be
allowed to get out of sync in future updates.

13. Options not in -Wall should follow.

I believe that this organization would be superior to, say, alphabetizing
the options.

Stephan T. Lavavej
http://stl.caltech.edu

RE: PATCH for: Lots of suggestions for the gcc manual

[Gerald Pfeifer]

On Sat, 4 Oct 2003, Stephan T. Lavavej wrote:
> Other things I've noticed:
>> You can request many specific warnings with options beginning -W, for
>> example -Wimplicit to request warnings on implicit declarations. Each of
>> these specific warning options also has a negative form beginning -Wno- to
>> turn off warnings; for example, -Wno-implicit.
> These sentences should be parallel 8 [...]

I agree.  Would you mind try and prepare a patch for this?  (Concerning
patches, it's often better to submit several, smaller ones than a jumbo
patch, for different reviewers may be needed and it's also simpler for
one reviewer to handle independent hunks.)

> Okay, here are my suggestions:

Let me pick some. ;-)

> -Wall
> Implies the following options:
> [ginormous list of options follows]

By this you mean the detailed documentation of options, not just a list
of options, I hope? Duplicate lists would constitute maintainance night-
mares.

> 6. Each option included in -Wall should say (in -Wall).
>
> 7. -Wall should be followed by the options that it turns on.  This need not
> be a contiguous block, since (1) -Wall won't say "all of the previous
> options combined" anymore, and (2) each option included in -Wall says so.
> Still, grouping them rather tightly is the clearest way to go about things.

Agreed.

> 9. -Wimplicit is another option like -Wall, even though it only has two
> things in it.
>
> 10. -Wunused is yet another option like -Wall.  (It's all this nesting and
> chains of implications that makes the current organization so unwieldy.)

Yes, and no. What should become (or remain) clear from the documentation
is that -Wall somehow is the set of warnings that we recommend, somehow,
and where no problems should exist to make code -Wall clean.

> 11. After (in -Wall) has been added to the appropriate functions, their
> descriptions should be grepped to make sure they don't mention that they're
> included in -Wall.

Yes. Perhaps you could start by hacking a patch to address the issues
related to -Wall?

> I believe that this organization would be superior to, say,
> alphabetizing the options.

In a printed manual, alphabetical ordering is quite useful, so I'd
hesitate to have much more than two sections (-Wall and non-Wall)
each of which is sorted alphabetically.  But that's just my preference,
I'd certainly be interested the others'!

Gerald
-- 
Gerald Pfeifer (Jerry)   gerald@pfeifer.com   http://www.pfeifer.com/gerald/

[PATCH] GCC Warning Options Documentation

[Stephan T. Lavavej]

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

Re: [PATCH] GCC Warning Options Documentation

[James Morrison]

"Stephan T. Lavavej" <stl@caltech.edu> writes:

> 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.)

 You'll want to check out the contributing to gcc webpage:
http://gcc.gnu.org/contribute.html#docchanges .
You can look at the dvi files using xdvi to check to see if your changes 
look correct in the printed format.

> 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 -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{)}

 This seems inconsistent with the rest of the GCC documentation.  Why not
list under -Wall what options it implies.  We can do the same thing with
-Wextra.  I'm thinking something like we do in invoke.texi for -O[123]

 Ok, I looked some more.  It seems that each optimizatation lists what
level enables it.  However, that is done as the last line of the description,
not as part of the item name.

> -@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}.

 I find this confusing.  Why not use:

This option turns on all the options begining with @samp{-Wunused} except
for @option{-Wunused-parameter}.  However, if @option{-Wextra} is used
then @samp{@-Wunused} also turns on @option{-Wunused-parameter}.

Jim

Re: [PATCH] GCC Warning Options Documentation

[Gerald Pfeifer]

On Sun, 15 Feb 2004, Stephan T. Lavavej wrote:
> 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.

This all looks fine -- sorry for failing to respond earlier!  (In general
it's easier to review smaller patches.)

Would you mind providing a ChangeLog, reformat your patch to avoid long
lines (>77 characters) in added/changed stuff, and resend your patch?
I'll be offline next week, so I'm Cc:ing Joseph.  Joseph, would you mind
having a look then?

> 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.)

You can do `make dvi` at the top level, for example.

Gerald
-- 
Gerald Pfeifer (Jerry)   gerald@pfeifer.com   http://www.pfeifer.com/gerald/