Lots of suggestions for the gcc manual

[Stephan Thomas Lavavej <stl@caltech.edu>]

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