Patchwork [wwwdocs] Add section on diagnostics conventions

login
register
mail settings
Submitter Diego Novillo
Date Feb. 1, 2012, 1:50 a.m.
Message ID <CAD_=9DQOyzUg2gRC6Y01dC3DYVpMxW=VoW1v8=sdfZupcUF2ng@mail.gmail.com>
Download mbox | patch
Permalink /patch/138890/
State New
Headers show

Comments

Diego Novillo - Feb. 1, 2012, 1:50 a.m.
On Mon, Jan 30, 2012 at 15:21, Joseph S. Myers <joseph@codesourcery.com> wrote:
> On Sun, 29 Jan 2012, Diego Novillo wrote:
>
>> +<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>
>
> The three sentences in this last list item are actually three independent
> and unrelated points.  I think the first one about assertion failures
> should be moved up into the previous list item, while the remaining two
> sentences should each be a list item on its own.

Thanks.  Fixed with the patch below.
Gabriel Dos Reis - Feb. 1, 2012, 12:01 p.m.
On Tue, Jan 31, 2012 at 7:50 PM, Diego Novillo <dnovillo@google.com> wrote:
> On Mon, Jan 30, 2012 at 15:21, Joseph S. Myers <joseph@codesourcery.com> wrote:
>> On Sun, 29 Jan 2012, Diego Novillo wrote:
>>
>>> +<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>
>>
>> The three sentences in this last list item are actually three independent
>> and unrelated points.  I think the first one about assertion failures
>> should be moved up into the previous list item, while the remaining two
>> sentences should each be a list item on its own.
>
> Thanks.  Fixed with the patch below.
>
>
> 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      1 Feb 2012 01:47:55 -0000
> @@ -157,6 +157,47 @@ 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>

Yes.

> +
> +<li>Diagnostics using the GCC diagnostic functions should generally
> +use the GCC-specific formats such as <code>%qs</code> or
> +<code>%&lt;</code> and <code>%&gt;</code> for quoting and
> +<code>%m</code> for <code>errno</code> numbers.</li>

Yes.

> +
> +<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>

Yes.

> +
> +<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>

OK.

> +
> +<li><code>error</code> is for defects in the user's code.</li>

Yes.

<code>sorry</code> is for correct user input programs but unimplemented
functionalities.  <code>warning</code> is for advisory diagnostics; it
may be used for diagnostics that have severity less than an error.
<code>inform</code> is for adding additional explanatory information to a
diagnostic.

> +
> +<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).  Assertion failures should not be triggered by
> +invalid input.</li>
OK.

> +
> +<li><code>inform</code> is for informative notes accompanying errors
> +and warnings.</li>
> +
> +<li>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.

Patch

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      1 Feb 2012 01:47:55 -0000
@@ -157,6 +157,47 @@  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>%&lt;</code> and <code>%&gt;</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).  Assertion failures should not be triggered by
+invalid input.</li>
+
+<li><code>inform</code> is for informative notes accompanying errors
+and warnings.</li>
+
+<li>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.