| Message ID | 4F25C15B.7080007@google.com |
|---|---|
| State | New |
| Headers | show |
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.
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.
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.
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>%<</code> and <code>%></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
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>%<</code> and<code>%></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.
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.