Patchwork [wwwdocs] Add section on diagnostics conventions

login
register
mail settings
Submitter Diego Novillo
Date Jan. 29, 2012, 9:59 p.m.
Message ID <4F25C15B.7080007@google.com>
Download mbox | patch
Permalink /patch/138478/
State New
Headers show

Comments

Diego Novillo - Jan. 29, 2012, 9:59 p.m.
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.
Joseph S. Myers - Jan. 30, 2012, 3:21 p.m.
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.
Gabriel Dos Reis - Jan. 31, 2012, 12:38 a.m.
On Mon, Jan 30, 2012 at 9:21 AM, 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.

Agreed.
Joseph S. Myers - Jan. 31, 2012, 4:35 p.m.
On Mon, 30 Jan 2012, Gabriel Dos Reis wrote:

> On Mon, Jan 30, 2012 at 9:21 AM, 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.
> 
> Agreed.

Thanks.  What do you think of the substance of the proposed additions?  
We're hoping that you can review whether the principles being documented 
for how to use diagnostic facilities are an accurate description of the 
coding standards that should be followed - and in general, we hope that 
maintainers of parts of the compiler will review documentation we add for 
previously undocumented coding standards relating to those parts.
Georg-Johann Lay - Feb. 1, 2012, 5:15 p.m.
Diego Novillo wrote:
> 
> 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>%&lt;</code> and <code>%&gt;</code> for quoting and
> +<code>%m</code> for <code>errno</code> numbers.</li>

A link to respective documentation would be greatly appreciated, i.e. a link to
the internals section describing the %-codes for diagnostic or a link to the
source file's comments.

Yes, I know it's in the sources. But guess you searched for documentation and
correct usage of %D. It will take you quite some time to find it in the sources...

Johann
Diego Novillo - Feb. 2, 2012, 3:03 a.m.
On Wed Feb  1 09:15:51 2012, Georg-Johann Lay wrote:
> Diego Novillo wrote:
>>
>> 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>%&lt;</code>  and<code>%&gt;</code>  for quoting and
>> +<code>%m</code>  for<code>errno</code>  numbers.</li>
>
> A link to respective documentation would be greatly appreciated, i.e. a link to
> the internals section describing the %-codes for diagnostic or a link to the
> source file's comments.
>
> Yes, I know it's in the sources. But guess you searched for documentation and
> correct usage of %D. It will take you quite some time to find it in the sources...

Sadly, these modifiers are not documented in gcc/doc/, the only 
documentation I know of is in gcc/pretty-print.c.  I think it would be 
a great idea to also document them in the .texi sources.  Would you be 
willing to prepare a patch?


Thanks.  Diego.

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      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>%&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).</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.