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.</p> +<h2>Diagnostics Conventions</h2> +<ul> + +<li>Use of the <code>input_location</code> global, and of the +diagnostic functions that implicitly use <code>input_location</code>, +is deprecated; the preferred technique is to pass around locations +ultimately derived from the location of some explicitly chosen source +code token.</li> + +<li>Diagnostics using the GCC diagnostic functions should generally +use the GCC-specific formats such as <code>%qs</code> or +<code>%<</code> and <code>%></code> for quoting and +<code>%m</code> for <code>errno</code> numbers.</li> + +<li>Identifiers should generally be formatted with <code>%E</code> or +<code>%qE</code>; use of <code>identifier_to_locale</code> is needed +if the identifier text is used directly.</li> + +<li>Formats such as <code>%wd</code> should be used with types such as +<code>HOST_WIDE_INT</code> (<code>HOST_WIDE_INT_PRINT_DEC</code> is a +format for the host <code>printf</code> functions, not for the GCC +diagnostic functions).</li> + +<li><code>error</code> is for defects in the user's code.</li> + +<li><code>internal_error</code> 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 <code>error</code> before further information is printed and +an ICE is triggered).</li> + +<li>Assertion failures should not be triggered by invalid input. +<code>inform</code> is for informative notes accompanying errors and +warnings. All diagnostics should be full sentences without English +fragments substituted in them, to facilitate translation.</li> + +</ul> + + <h2>Miscellaneous Conventions</h2> <p>Code should use <code>gcc_assert(EXPR)</code> to check invariants.
