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

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

[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