From patchwork Thu Feb 2 03:07:10 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Diego Novillo X-Patchwork-Id: 139078 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 E6E70104785 for ; Thu, 2 Feb 2012 14:07:35 +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=1328756856; h=Comment: DomainKey-Signature:Received:Received:Received:Received:Received: Received:Received:Message-ID:Date:From:User-Agent:MIME-Version: To:CC:Subject:References:In-Reply-To:Content-Type:Mailing-List: Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:Sender:Delivered-To; bh=u8U0WnP8PfGT1BA94uYt8Oktb8M=; b=b7szCM/oBy5WEIx0BfyQBmZ6BChNmuRFvpz6Fy2j0muTLC2YBZM/mcKSqd0IP0 SORBNCiAP9X5ULxhzRFEf7nCnhuHRE3AhI+0BrN90kl4z/ktgmrKo05QEPu48E0w m/xH8qXiWS5GDB6f2nu+Gc1tjTWPRi9aRcKSckBsQDAOw= 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:CC:Subject:References:In-Reply-To:Content-Type:X-IsSubscribed:Mailing-List:Precedence:List-Id:List-Unsubscribe:List-Archive:List-Post:List-Help:Sender:Delivered-To; b=AvlFLqRDUXwuQxfzzu32V6mFnM/q8YL5krcWV8gU18TYx/UeSMMABLVpp2UEQH z73v5O3Ig/WXZe1GPQv7KsGE8cIj76G70lslupLZL8pqloddcwHMmmxqoBxHZuTL eq4aHVWU1KmPS2HAbtMEEnsdrRDri5qnY9wk03Qen97fs=; Received: (qmail 21265 invoked by alias); 2 Feb 2012 03:07:30 -0000 Received: (qmail 21253 invoked by uid 22791); 2 Feb 2012 03:07:29 -0000 X-SWARE-Spam-Status: No, hits=-2.7 required=5.0 tests=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-tul01m020-f175.google.com (HELO mail-tul01m020-f175.google.com) (209.85.214.175) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 02 Feb 2012 03:07:16 +0000 Received: by obhx4 with SMTP id x4so2511832obh.20 for ; Wed, 01 Feb 2012 19:07:15 -0800 (PST) Received: by 10.50.155.193 with SMTP id vy1mr1325228igb.14.1328152035572; Wed, 01 Feb 2012 19:07:15 -0800 (PST) Received: by 10.50.155.193 with SMTP id vy1mr1325213igb.14.1328152035465; Wed, 01 Feb 2012 19:07:15 -0800 (PST) Received: from dhcp-172-19-14-89.mtv.corp.google.com ([2620:0:1000:2104:e2f8:47ff:fe39:637a]) by mx.google.com with ESMTPS id g34sm2049742ibk.10.2012.02.01.19.07.11 (version=SSLv3 cipher=OTHER); Wed, 01 Feb 2012 19:07:13 -0800 (PST) Message-ID: <4F29FDDE.2070405@google.com> Date: Wed, 01 Feb 2012 19:07:10 -0800 From: Diego Novillo User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:10.0) Gecko/20120129 Thunderbird/10.0 MIME-Version: 1.0 To: Gabriel Dos Reis CC: "Joseph S. Myers" , gcc-patches Subject: Re: [wwwdocs] Add section on diagnostics conventions References: <4F25C15B.7080007@google.com> In-Reply-To: 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 Thanks. I've incorporated your feedback in the attached patch. OK for wwwdocs? Diego. ? 00.diff ? codingconventions.html.orig 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 2 Feb 2012 03:06:00 -0000 @@ -157,6 +157,57 @@ 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.
    • + +
  • sorry is for correct user input programs but +unimplemented functionalities.
    • + +
  • warning is for advisory diagnostics; it +may be used for diagnostics that have severity less than an +error.
    • + +
  • inform is for adding additional explanatory +information to a diagnostic.
    • + +
  • 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.