Re: [PATCH] GCC Warning Options Documentation

[James Morrison <ja2morri at csclub dot uwaterloo dot ca>]

"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