From patchwork Sun Jan 29 21:59:55 2012
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
X-Patchwork-Submitter: Diego Novillo
X-Patchwork-Id: 138478
Return-Path:
X-Original-To: incoming@patchwork.ozlabs.org
Delivered-To: patchwork-incoming@bilbo.ozlabs.org
Received: from sourceware.org (server1.sourceware.org [209.132.180.131])
by ozlabs.org (Postfix) with SMTP id A9FFEB6EFE
for ;
Mon, 30 Jan 2012 09:00:22 +1100 (EST)
Comment: DKIM? See http://www.dkim.org
DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed;
d=gcc.gnu.org; s=default; x=1328479224; h=Comment:
DomainKey-Signature:Received:Received:Received:Received:Received:
Received:Received:Message-ID:Date:From:User-Agent:MIME-Version:
To:Subject:Content-Type:Content-Transfer-Encoding:Mailing-List:
Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:
List-Help:Sender:Delivered-To; bh=06bVPN5+ODGZpeZgaPQJsb0FW4A=;
b=Lg4IdNwCV181K2Qgl/ClkbK+/JBMTRUJa/3En/ohYlAf/5EVQCVGvxN3Xv5HQd
wc10fnO0IuWzwlTZ5iEnCUQtmCMi8BBCMhfcKQ10IboFasLAC4NuEgiKkB5wjaHX
zdajonT51qQsgTmEq5fy9fAHgnqxZXWe/NNtZS6xduOp0=
Comment: DomainKeys? See http://antispam.yahoo.com/domainkeys
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=default; d=gcc.gnu.org;
h=Received:Received:X-SWARE-Spam-Status:X-Spam-Check-By:Received:Received:Received:Received:Received:Message-ID:Date:From:User-Agent:MIME-Version:To:Subject:Content-Type:Content-Transfer-Encoding:X-IsSubscribed:Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:List-Help:Sender:Delivered-To;
b=DjJLqLC/ZWu5l7ShSNEijfq/RTljIuWoWZREgM0Jd+81KCC/5g+ndSPzcwqqq3
lYPQCuTbaTeOJD0pVF+9ZAg626iu2X8rQUVZOzfsCfvQ6yAmKJErAMVF7pqK69dL
L1eGqgfBNuq/nJdms/4OrnPbXuWjaUOvC20DLCz6mUpWI=;
Received: (qmail 31713 invoked by alias); 29 Jan 2012 22:00:13 -0000
Received: (qmail 31698 invoked by uid 22791); 29 Jan 2012 22:00:12 -0000
X-SWARE-Spam-Status: No, hits=-2.9 required=5.0 tests=AWL, BAYES_00,
DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, RCVD_IN_DNSWL_LOW,
T_RP_MATCHES_RCVD
X-Spam-Check-By: sourceware.org
Received: from mail-qw0-f54.google.com (HELO mail-qw0-f54.google.com)
(209.85.216.54) by sourceware.org (qpsmtpd/0.43rc1) with
ESMTP; Sun, 29 Jan 2012 21:59:59 +0000
Received: by qaea17 with SMTP id a17so2376967qae.20 for
; Sun, 29 Jan 2012 13:59:58 -0800 (PST)
Received: by 10.224.180.142 with SMTP id bu14mr18268702qab.30.1327874398182;
Sun, 29 Jan 2012 13:59:58 -0800 (PST)
Received: by 10.224.180.142 with SMTP id bu14mr18268687qab.30.1327874398045;
Sun, 29 Jan 2012 13:59:58 -0800 (PST)
Received: from dnovillo-macbookpro.local ([72.14.228.1]) by mx.google.com
with ESMTPS id r17sm30699725qap.11.2012.01.29.13.59.56
(version=SSLv3 cipher=OTHER); Sun, 29 Jan 2012 13:59:57 -0800 (PST)
Message-ID: <4F25C15B.7080007@google.com>
Date: Sun, 29 Jan 2012 16:59:55 -0500
From: Diego Novillo
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6;
rv:9.0) Gecko/20111222 Thunderbird/9.0.1
MIME-Version: 1.0
To: Gabriel Dos Reis ,
"Joseph S. Myers" ,
gcc-patches
Subject: [wwwdocs] Add section on diagnostics conventions
X-IsSubscribed: yes
Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm
Precedence: bulk
List-Id:
List-Unsubscribe:
List-Archive:
List-Post:
List-Help:
Sender: gcc-patches-owner@gcc.gnu.org
Delivered-To: mailing list gcc-patches@gcc.gnu.org
This is the first of a few patches to update GCC's documentation with
the proposed conventions in the GCC Development Conventions document
that Joseph and I published last year
(https://docs.google.com/a/google.com/document/pub?id=10LO8y0YhjlKHya_PKM3jEGrJu0rllv-Nc9qP5LXqH_I#h.qpg2rjcas9fw)
I am just starting to get back to these documents, so I will start with
the "easy" parts. Joseph, Gabriel, I'm sending this patch to you since
you folks maintain these areas. Other changes to the documentation may
need global reviewers.
OK for wwwdocs?
Diego.
Index: codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.63
diff -u -d -u -p -r1.63 codingconventions.html
--- codingconventions.html 12 Feb 2011 15:49:51 -0000 1.63
+++ codingconventions.html 29 Jan 2012 21:51:56 -0000
@@ -157,6 +157,45 @@ regression-checkers distinguish a true r
to the test suite.
+Diagnostics Conventions
+
+
+- Use of the
input_location
global, and of the
+diagnostic functions that implicitly use input_location
,
+is deprecated; the preferred technique is to pass around locations
+ultimately derived from the location of some explicitly chosen source
+code token.
+
+- Diagnostics using the GCC diagnostic functions should generally
+use the GCC-specific formats such as
%qs
or
+%<
and %>
for quoting and
+%m
for errno
numbers.
+
+- Identifiers should generally be formatted with
%E
or
+%qE
; use of identifier_to_locale
is needed
+if the identifier text is used directly.
+
+- Formats such as
%wd
should be used with types such as
+HOST_WIDE_INT
(HOST_WIDE_INT_PRINT_DEC
is a
+format for the host printf
functions, not for the GCC
+diagnostic functions).
+
+error
is for defects in the user's code.
+
+internal_error
is used for conditions that should not
+be triggered by any user input whether valid or invalid and including
+invalid asms and LTO binary data (sometimes, as an exception, there is
+a call to error
before further information is printed and
+an ICE is triggered).
+
+- Assertion failures should not be triggered by invalid input.
+
inform
is for informative notes accompanying errors and
+warnings. All diagnostics should be full sentences without English
+fragments substituted in them, to facilitate translation.
+
+
+
+
Miscellaneous Conventions
Code should use gcc_assert(EXPR)
to check invariants.