Re: [wwwdocs] Add section on diagnostics conventions

[Diego Novillo]

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.