gnat_rm.texi: Document Reason argument for pragma Warnings.

2013-04-25  Robert Dewar  <dewar@adacore.com>

	* gnat_rm.texi: Document Reason argument for pragma Warnings.
	* par-prag.adb: Handle Reason parameter for pragma Warnings.
	* sem_prag.adb (Analyze_Pragma, case Warnings): Allow Reason argument.
	* snames.ads-tmpl (Name_Reason): New name entry.

From-SVN: r198295

1 files changed, 23 insertions, 10 deletions

diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 5c1a547..7f3596b 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -6520,10 +6520,12 @@ implementation in DEC Ada 83.
 Syntax:
 
 @smallexample @c ada
-pragma Warnings (On | Off);
-pragma Warnings (On | Off, LOCAL_NAME);
-pragma Warnings (static_string_EXPRESSION);
-pragma Warnings (On | Off, static_string_EXPRESSION);
+pragma Warnings (On | Off [,REASON]);
+pragma Warnings (On | Off, LOCAL_NAME [,REASON]);
+pragma Warnings (static_string_EXPRESSION [,REASON]);
+pragma Warnings (On | Off, static_string_EXPRESSION [,REASON]);
+
+REASON ::= Reason => static_string_EXPRESSION
 @end smallexample
 
 @noindent
@@ -6531,17 +6533,28 @@ Normally warnings are enabled, with the output being controlled by
 the command line switch.  Warnings (@code{Off}) turns off generation of
 warnings until a Warnings (@code{On}) is encountered or the end of the
 current unit.  If generation of warnings is turned off using this
-pragma, then no warning messages are output, regardless of the
-setting of the command line switches.
+pragma, then some or all of the warning messages are suppressed,
+regardless of the setting of the command line switches.
+
+The @code{Reason} parameter may optionally appear as the last argument
+in any of the forms of this pragma. It is intended purely for the
+purposes of documenting the reason for the @code{Warnings} pragma.
+The compiler will check that the argument is a static string but
+otherwise ignore this argument. Other tools may provide specialized
+processing for this string.
 
-The form with a single argument may be used as a configuration pragma.
+The form with a single argument (or two arguments if Reason present),
+where the first argument is @code{ON} or @code{OFF}
+may be used as a configuration pragma.
 
 If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
 the specified entity.  This suppression is effective from the point where
 it occurs till the end of the extended scope of the variable (similar to
-the scope of @code{Suppress}).
+the scope of @code{Suppress}). This form cannot be used as a configuration
+pragma.
 
-The form with a single static_string_EXPRESSION argument provides more precise
+The form with a single static_string_EXPRESSION argument (and possible
+reason) provides more precise
 control over which warnings are active. The string is a list of letters
 specifying which warnings are to be activated and which deactivated. The
 code for these letters is the same as the string used in the command
@@ -6549,7 +6562,7 @@ line switch controlling warnings. For a brief summary, use the gnatmake
 command with no arguments, which will generate usage information containing
 the list of warnings switches supported. For
 full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
-User's Guide}.
+User's Guide}. This form can also be used as a configuration pragma.
 
 @noindent
 The warnings controlled by the `-gnatw' switch are generated by the front end