gnat_rm.texi, [...]: Update gnatcheck doc.

2010-01-27  Sergey Rybin  <rybin@adacore.com>

	* gnat_rm.texi, gnat_ugn.texi: Update gnatcheck doc.

From-SVN: r156279

3 files changed, 211 insertions, 1 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 814961b..9674a20 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,7 @@
+2010-01-27  Sergey Rybin  <rybin@adacore.com>
+
+	* gnat_rm.texi, gnat_ugn.texi: Update gnatcheck doc.
+
 2010-01-27  Robert Dewar  <dewar@adacore.com>
 
 	* sinput.ads, sinput.adb (Sloc_Range): Applies to all nodes, formal
diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi
index 46823f9..abfb4ee 100644
--- a/gcc/ada/gnat_rm.texi
+++ b/gcc/ada/gnat_rm.texi
@@ -16454,7 +16454,7 @@ package_spec ::=
 package_identifier ::=
   @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
   @code{Linker} | @code{Finder}  | @code{Cross_Reference} |
-  @code{gnatls} | @code{IDE}     | @code{Pretty_Printer}
+  @code{gnatls} | @code{IDE}     | @code{Pretty_Printer} | @code{Check}
 @end smallexample
 
 @subsection Package Naming
@@ -16775,6 +16775,25 @@ be called with the options specified by Default_Switches of its language,
 if defined.
 @end table
 
+@subsection package Check
+
+@noindent
+The attributes of package @code{Check}
+specify the checking rule options to be used
+when invoking the checking tool @command{gnatcheck}.
+The following attributes apply to package @code{Check}:
+
+@table @code
+@item     Default_switches
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatcheck} on a source
+written in that language. The first string in the range should always be
+@code{"-rules"} to specify that all the other options belong to the
+@code{-rules} section of the parameters of @command{gnatcheck} call.
+
+@end table
+
 @subsection package Pretty_Printer
 
 @noindent
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 9d35f8e..ab52d63 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -492,6 +492,7 @@ Verifying Properties Using gnatcheck
 * Project-Wide Checks::
 * Rule exemption::
 * Predefined Rules::
+* Example of gnatcheck Usage::
 
 Sample Bodies Using gnatstub
 
@@ -12719,6 +12720,8 @@ case insensitive. The following package names are legal:
 @item
 @code{Cross_Reference}
 @item
+@code{Check}
+@item
 @code{Eliminate}
 @item
 @code{Pretty_Printer}
@@ -14926,6 +14929,10 @@ package @code{Gnatstub} for command STUB
 package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
 
 @item
+package @code{Check} for command CHECK
+(invoking @code{^gnatcheck^gnatcheck^})
+
+@item
 package @code{Metrics} for command METRIC
 (invoking @code{^gnatmetric^gnatmetric^})
 
@@ -20736,6 +20743,7 @@ supplied.
 * Project-Wide Checks::
 * Rule exemption::
 * Predefined Rules::
+* Example of gnatcheck Usage::
 @end menu
 
 @node Format of the Report File
@@ -22933,6 +22941,185 @@ Only variable declarations, and not constant declarations, are checked.
 
 This rule has no parameters.
 
+@node Example of gnatcheck Usage
+@section Example of @command{gnatcheck} Usage
+
+@noindent
+Here is a simple example. Suppose that in the current directory we have a
+project file named @file{gnatcheck_example.gpr} with the following content:
+
+@smallexample @c projectfile
+project Gnatcheck_Example is
+
+   for Source_Dirs use ("src");
+   for Object_Dir use "obj";
+   for Main use ("main.adb");
+
+   package Check is
+      for Default_Switches ("ada") use ("-rules", "-from=coding_standard");
+   end Check;
+
+end Gnatcheck_Example;
+@end smallexample
+
+@noindent
+And the file named @file{coding_standard} is also located in the current
+directory and has the following content:
+
+@smallexample
+-----------------------------------------------------
+-- This is a sample gnatcheck coding standard file --
+-----------------------------------------------------
+
+--  First, turning on rules, that are directly implemented in gnatcheck
++RAbstract_Type_Declarations
++RAnonymous_Arrays
++RLocal_Packages
++RFloat_Equality_Checks
++REXIT_Statements_With_No_Loop_Name
+
+--  Then, activating compiler checks of interest:
++RStyle_Checks:e
+--  This style check checks if a unit name is present on END keyword that
+--  is the end of the unit declaration
+@end smallexample
+
+@noindent
+And the subdirectory @file{src} contains the following Ada sources:
+
+@file{pack.ads}:
+
+@smallexample @c ada
+package Pack is
+   type T is abstract tagged private;
+   procedure P (X : T) is abstract;
+
+   package Inner is
+      type My_Float is digits 8;
+      function Is_Equal (L, R : My_Float) return Boolean;
+   end Inner;
+private
+   type T is abstract tagged null record;
+end;
+@end smallexample
+
+@noindent
+@file{pack.adb}:
+
+@smallexample @c ada
+package body Pack is
+   package body Inner is
+      function Is_Equal (L, R : My_Float) return Boolean is
+      begin
+         return L = R;
+      end;
+   end Inner;
+end Pack;
+@end smallexample
+
+@noindent
+and @file{main.adb}
+
+@smallexample @c ada
+with Pack; use Pack;
+procedure Main is
+
+   pragma Annotate
+     (gnatcheck, Exempt_On, "Anonymous_Arrays", "this one is fine");
+   Float_Array : array (1 .. 10) of Inner.My_Float;
+   pragma Annotate (gnatcheck, Exempt_Off, "Anonymous_Arrays");
+
+   Another_Float_Array : array (1 .. 10) of Inner.My_Float;
+
+   use Inner;
+
+   B : Boolean := False;
+
+begin
+   for J in Float_Array'Range loop
+      if Is_Equal (Float_Array (J), Another_Float_Array (J)) then
+         B := True;
+         exit;
+      end if;
+   end loop;
+end Main;
+@end smallexample
+
+@noindent
+And suppose we call @command{gnatcheck} from the current directory using
+the @command{gnat} driver:
+
+@smallexample
+   gnat check -Pgnatcheck_example.gpr
+@end smallexample
+
+@noindent
+As a result, @command{gnatcheck} is called to check all the files from the
+project @file{gnatcheck_example.gpr} using the coding standard defined by
+the file @file{coding_standard}. As the result, the @command{gnatcheck}
+report file named @file{gnatcheck.out} will be created in the current
+directory, and it will have the following content:
+
+@smallexample
+RULE CHECKING REPORT
+
+1. OVERVIEW
+
+Date and time of execution: 2009.10.28 14:17
+Tool version: GNATCHECK (built with ASIS 2.0.R for GNAT Pro 6.3.0w (20091016))
+Command line:
+
+gnatcheck -files=.../GNAT-TEMP-000004.TMP -cargs -gnatec=.../GNAT-TEMP-000003.TMP -rules -from=coding_standard
+
+Coding standard (applied rules):
+   Abstract_Type_Declarations
+   Anonymous_Arrays
+   EXIT_Statements_With_No_Loop_Name
+   Float_Equality_Checks
+   Local_Packages
+
+   Compiler style checks: -gnatye
+
+Number of coding standard violations: 6
+Number of exempted coding standard violations: 1
+
+2. DETECTED RULE VIOLATIONS
+
+2.1. NON-EXEMPTED VIOLATIONS
+
+Source files with non-exempted violations
+   pack.ads
+   pack.adb
+   main.adb
+
+List of violations grouped by files, and ordered by increasing source location:
+
+pack.ads:2:4: declaration of abstract type
+pack.ads:5:4: declaration of local package
+pack.ads:10:30: declaration of abstract type
+pack.ads:11:1: (style) "end Pack" required
+pack.adb:5:19: use of equality operation for float values
+pack.adb:6:7: (style) "end Is_Equal" required
+main.adb:9:26: anonymous array type
+main.adb:19:10: exit statement with no loop name
+
+2.2. EXEMPTED VIOLATIONS
+
+Source files with exempted violations
+   main.adb
+
+List of violations grouped by files, and ordered by increasing source location:
+
+main.adb:6:18: anonymous array type
+   (this one is fine)
+
+2.3. SOURCE FILES WITH NO VIOLATION
+
+   No files without violations
+
+END OF REPORT
+@end smallexample
+
 
 @c *********************************
 @node Creating Sample Bodies Using gnatstub