[PATCH] update -Wall and -Wextra documentation

[PATCH] update -Wall and -Wextra documentation

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 373 bytes --]

A number of warning options are missing from the list shown under
-Wall (for example, -Winit-self, -Wlogical-not-parentheses, and
-Wplacement-new).  The patch adds the missing ones and adjusts
some of the existing ones to maintain an alphabetical order.  It
also makes a couple of minor clarifications to -Wextra, and adds
an example to the -Wplacement-new option.

Martin

[-- Attachment #2: gcc-wall-doc.patch --]
[-- Type: text/x-patch, Size: 3236 bytes --]

2015-12-09  Martin Sebor  <msebor@redhat.com>

	* invoke.texi (Warning Options): Update -Wall options.  Clarify
	when some -Wextra options are enabled.  Add -Wplacement-new example.

Index: invoke.texi
===================================================================
--- invoke.texi	(revision 231436)
+++ invoke.texi	(working copy)
@@ -3541,26 +3541,33 @@
 
 @gccoptlist{-Waddress   @gol
 -Warray-bounds=1 @r{(only with} @option{-O2}@r{)}  @gol
+-Wbool-compare  @gol
 -Wc++11-compat  -Wc++14-compat@gol
 -Wchar-subscripts  @gol
+-Wcomment  @gol
+-Wduplicated-cond  @gol
 -Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
+-Wformat   @gol
+-Wimplicit @r{(C and Objective-C only)} @gol
 -Wimplicit-int @r{(C and Objective-C only)} @gol
 -Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
--Wbool-compare  @gol
--Wduplicated-cond  @gol
--Wcomment  @gol
--Wformat   @gol
+-Winit-self @r{(only for C++)} @gol
+-Wlogical-not-parentheses
 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)}  @gol
 -Wmaybe-uninitialized @gol
+-Wmemset-transposed-args @gol
 -Wmissing-braces @r{(only for C/ObjC)} @gol
+-Wnarrowing @r{(only for C++)}  @gol
 -Wnonnull  @gol
 -Wopenmp-simd @gol
 -Wparentheses  @gol
+-Wplacement-new @r{(only for C++)} @gol
 -Wpointer-sign  @gol
 -Wreorder   @gol
 -Wreturn-type  @gol
 -Wsequence-point  @gol
 -Wsign-compare @r{(only in C++)}  @gol
+-Wsizeof-pointer-memaccess @gol
 -Wstrict-aliasing  @gol
 -Wstrict-overflow=1  @gol
 -Wswitch  @gol
@@ -3598,10 +3605,10 @@
 -Wmissing-parameter-type @r{(C only)}  @gol
 -Wold-style-declaration @r{(C only)}  @gol
 -Woverride-init  @gol
--Wsign-compare  @gol
+-Wsign-compare @r{(C only)} @gol
 -Wtype-limits  @gol
 -Wuninitialized  @gol
--Wshift-negative-value  @gol
+-Wshift-negative-value @r{(in C++03 and in C99 and newer)}  @gol
 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
 -Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}  @gol
 }
@@ -4895,8 +4902,15 @@
 @opindex Wno-placement-new
 Warn about placement new expressions with undefined behavior, such as
 constructing an object in a buffer that is smaller than the type of
-the object.
-
+the object.  For example, the placement new expression below is diagnosed
+because it attempts to construct an array of 64 integers in a buffer only
+64 bytes large.
+@smallexample
+char buf [64];
+new (buf) int[64];
+@end smallexample
+This warning is enabled by @option{-Wall}.
+  
 @item -Wpointer-arith
 @opindex Wpointer-arith
 @opindex Wno-pointer-arith
@@ -5113,8 +5127,9 @@
 @cindex signed and unsigned values, comparison warning
 Warn when a comparison between signed and unsigned values could produce
 an incorrect result when the signed value is converted to unsigned.
-This warning is also enabled by @option{-Wextra}; to get the other warnings
-of @option{-Wextra} without this warning, use @option{-Wextra -Wno-sign-compare}.
+In C++, this warning is also enabled by @option{-Wall}.  In C, it is also
+enabled by @option{-Wextra}; to get the other warnings of @option{-Wextra}
+without this warning, use @option{-Wextra -Wno-sign-compare}.
 
 @item -Wsign-conversion
 @opindex Wsign-conversion

Re: [PATCH] update -Wall and -Wextra documentation

[Bernd Schmidt]

On 12/10/2015 12:07 AM, Martin Sebor wrote:
>
> 	* invoke.texi (Warning Options): Update -Wall options.  Clarify
> 	when some -Wextra options are enabled.  Add -Wplacement-new example.

I tried to check this list against c.opt - I figure this should contain 
essentially the ones that are have an EnabledBy(Wall), plus whatever 
logic there is in c-opts.

> +-Wduplicated-cond  @gol

I don't see this one as enabled by Wall, and

2015-10-02  Marek Polacek  <polacek@redhat.com>

	* c.opt (Wduplicated-cond): Don't enable by -Wall anymore.

> +-Wplacement-new @r{(only for C++)} @gol

This one appears to be on by default?

> +In C++, this warning is also enabled by @option{-Wall}.  In C, it is also
> +enabled by @option{-Wextra}; to get the other warnings of @option{-Wextra}
> +without this warning, use @option{-Wextra -Wno-sign-compare}.

Is the last part of the sentence really necessary? It kind of follows 
from the rest of the documentation and we don't spell this out for other 
-Wextra options.


Bernd

Re: [PATCH] update -Wall and -Wextra documentation

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 1976 bytes --]

On 12/10/2015 04:57 AM, Bernd Schmidt wrote:
> On 12/10/2015 12:07 AM, Martin Sebor wrote:
>>
>>     * invoke.texi (Warning Options): Update -Wall options.  Clarify
>>     when some -Wextra options are enabled.  Add -Wplacement-new example.
>
> I tried to check this list against c.opt - I figure this should contain
> essentially the ones that are have an EnabledBy(Wall), plus whatever
> logic there is in c-opts.

Thanks for double-checking me!  FWIW, I did something similar.
I also verified those I wasn't sure about them using simple
examples, but it's possible I overlooked something.

>
>> +-Wduplicated-cond  @gol
>
> I don't see this one as enabled by Wall, and

Yes, this one should not be there.  I removed it in the updated
patch.  (Note the first patch didn't add it, just moved it up
the list).

Incidentally, testing this using the example from the manual
triggers an ICE.  I raised c/68839 for the record and closed
it as a duplicate of c/68473.

>
>> +-Wplacement-new @r{(only for C++)} @gol
>
> This one appears to be on by default?

Hmm.  You're right, it is.  I'm not sure that's what we want
but let me confirm that with Jason and deal with it separately.
I've corrected the patch to reflect the status quo.

>
>> +In C++, this warning is also enabled by @option{-Wall}.  In C, it is
>> also
>> +enabled by @option{-Wextra}; to get the other warnings of
>> @option{-Wextra}
>> +without this warning, use @option{-Wextra -Wno-sign-compare}.
>
> Is the last part of the sentence really necessary? It kind of follows
> from the rest of the documentation and we don't spell this out for other
> -Wextra options.

I don't think explaining how to turn the option off is necessary
or adds any value but the text was already there and I didn't want
to make gratuitous changes unrelated to the main purpose of the
patch.  But if you think it's appropriate I'm fine with removing
it and have done that in the updated patch.

The updated patch is attached.

Martin

[-- Attachment #2: gcc-wall-doc.patch --]
[-- Type: text/x-patch, Size: 3245 bytes --]

2015-12-09  Martin Sebor  <msebor@redhat.com>

	* invoke.texi (Warning Options): Update -Wall options.  Clarify
	when some -Wextra options are enabled.  Add -Wplacement-new example.

Index: invoke.texi
===================================================================
--- invoke.texi	(revision 231525)
+++ invoke.texi	(working copy)
@@ -3542,18 +3542,22 @@
 
 @gccoptlist{-Waddress   @gol
 -Warray-bounds=1 @r{(only with} @option{-O2}@r{)}  @gol
+-Wbool-compare  @gol
 -Wc++11-compat  -Wc++14-compat@gol
 -Wchar-subscripts  @gol
+-Wcomment  @gol
 -Wenum-compare @r{(in C/ObjC; this is on by default in C++)} @gol
+-Wformat   @gol
+-Wimplicit @r{(C and Objective-C only)} @gol
 -Wimplicit-int @r{(C and Objective-C only)} @gol
 -Wimplicit-function-declaration @r{(C and Objective-C only)} @gol
--Wbool-compare  @gol
--Wduplicated-cond  @gol
--Wcomment  @gol
--Wformat   @gol
+-Winit-self @r{(only for C++)} @gol
+-Wlogical-not-parentheses
 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)}  @gol
 -Wmaybe-uninitialized @gol
+-Wmemset-transposed-args @gol
 -Wmissing-braces @r{(only for C/ObjC)} @gol
+-Wnarrowing @r{(only for C++)}  @gol
 -Wnonnull  @gol
 -Wopenmp-simd @gol
 -Wparentheses  @gol
@@ -3562,6 +3566,7 @@
 -Wreturn-type  @gol
 -Wsequence-point  @gol
 -Wsign-compare @r{(only in C++)}  @gol
+-Wsizeof-pointer-memaccess @gol
 -Wstrict-aliasing  @gol
 -Wstrict-overflow=1  @gol
 -Wswitch  @gol
@@ -3599,10 +3604,10 @@
 -Wmissing-parameter-type @r{(C only)}  @gol
 -Wold-style-declaration @r{(C only)}  @gol
 -Woverride-init  @gol
--Wsign-compare  @gol
+-Wsign-compare @r{(C only)} @gol
 -Wtype-limits  @gol
 -Wuninitialized  @gol
--Wshift-negative-value  @gol
+-Wshift-negative-value @r{(in C++03 and in C99 and newer)}  @gol
 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
 -Wunused-but-set-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)}  @gol
 }
@@ -4589,7 +4594,6 @@
 if (p->q != NULL) @{ @dots{} @}
 else if (p->q != NULL) @{ @dots{} @}
 @end smallexample
-This warning is enabled by @option{-Wall}.
 
 @item -Wframe-address
 @opindex Wno-frame-address
@@ -4896,8 +4900,15 @@
 @opindex Wno-placement-new
 Warn about placement new expressions with undefined behavior, such as
 constructing an object in a buffer that is smaller than the type of
-the object.
-
+the object.  For example, the placement new expression below is diagnosed
+because it attempts to construct an array of 64 integers in a buffer only
+64 bytes large.
+@smallexample
+char buf [64];
+new (buf) int[64];
+@end smallexample
+This warning is enabled by default.
+  
 @item -Wpointer-arith
 @opindex Wpointer-arith
 @opindex Wno-pointer-arith
@@ -5114,8 +5125,8 @@
 @cindex signed and unsigned values, comparison warning
 Warn when a comparison between signed and unsigned values could produce
 an incorrect result when the signed value is converted to unsigned.
-This warning is also enabled by @option{-Wextra}; to get the other warnings
-of @option{-Wextra} without this warning, use @option{-Wextra -Wno-sign-compare}.
+In C++, this warning is also enabled by @option{-Wall}.  In C, it is
+also enabled by @option{-Wextra}.
 
 @item -Wsign-conversion
 @opindex Wsign-conversion

Re: [PATCH] update -Wall and -Wextra documentation

[Bernd Schmidt]

On 12/10/2015 05:52 PM, Martin Sebor wrote:
>
> The updated patch is attached.

Ok.


Bernd