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.