From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17388 invoked by alias); 13 Sep 2003 10:51:35 -0000 Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org Received: (qmail 17371 invoked from network); 13 Sep 2003 10:51:27 -0000 Received: from unknown (HELO earth-ox.its.caltech.edu) (131.215.49.69) by sources.redhat.com with SMTP; 13 Sep 2003 10:51:27 -0000 Received: from fire-dog (fire-dog [192.168.1.4]) by earth-ox-postvirus (Postfix) with ESMTP id EAA55109A41 for ; Sat, 13 Sep 2003 03:51:26 -0700 (PDT) Received: from water-ox ([192.168.1.10]) by fire-dog (MailMonitor for SMTP v1.2.2 ) ; Sat, 13 Sep 2003 03:51:26 -0700 (PDT) Received: from blinky.its.caltech.edu (blinky.its.caltech.edu [131.215.48.132]) by water-ox.its.caltech.edu (Postfix) with ESMTP id F150C26AC3E for ; Sat, 13 Sep 2003 03:51:25 -0700 (PDT) Received: from localhost (stl@localhost) by blinky.its.caltech.edu (8.12.9/8.12.8) with ESMTP id h8DApPgA024887 for ; Sat, 13 Sep 2003 03:51:25 -0700 (PDT) X-Authentication-Warning: blinky.its.caltech.edu: stl owned process doing -bs Date: Sat, 13 Sep 2003 15:00:00 -0000 From: Stephan Thomas Lavavej X-X-Sender: stl@blinky To: gcc@gcc.gnu.org Subject: Lots of suggestions for the gcc manual Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-Spam-Status: No, hits=0.0 tagged_above=-100000.0 required=5.0 X-Spam-Level: X-SW-Source: 2003-09/txt/msg00600.txt.bz2 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