2007-09-26 Sergey Rybin <rybin@adacore.com>

	* vms_data.ads: Revise gnatmetric qualifiers.
	Add qualified for the new gnatbind option '-y'

	* gnat_ugn.texi: Revise the gnatmetric section.
	Add entry for new gnatbind option '-y'.

	* gnat_rm.texi: Minor spelling correction.
	Document restriction on overlaying controlled types



git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@128808 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 202 insertions, 79 deletions

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 9717fd040f3..0979412feb1 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -7659,6 +7659,10 @@ Default mode, in which sources are checked for consistency only if
 they are available.
 @end ifset
 
+@item ^-y^/ENABLE_LEAP_SECONDS^
+@cindex @option{^-y^/ENABLE_LEAP_SECONDS^} (@code{gnatbind})
+Enable leap seconds support in @code{Ada.Calendar} and its children.
+
 @item ^-z^/ZERO_MAIN^
 @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind})
 No main subprogram.
@@ -16293,9 +16297,7 @@ The following subsections describe the various switches accepted by
 @menu
 * Output Files Control::
 * Disable Metrics For Local Units::
-* Line Metrics Control::
-* Syntax Metrics Control::
-* Complexity Metrics Control::
+* Specifying a set of metrics to compute::
 * Other gnatmetric Switches::
 * Generate project-wide metrics::
 @end menu
@@ -16311,9 +16313,11 @@ output is generated.
 
 When generating the output in textual form, @command{gnatmetric} creates
 for each Ada source file a corresponding text file
-containing the computed metrics. By default, this file
-is placed in the same directory as where the source file is located, and
-its name is obtained
+containing the computed metrics, except for the case when the set of metrics
+specified by gnatmetric parameters consists only of metrics that are computed
+for the whole set of analyzed sources, but not for each Ada source.
+By default, this file is placed in the same directory as where the source
+file is located, and its name is obtained
 by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the
 input file.
 
@@ -16413,8 +16417,26 @@ Do not compute detailed metrics for eligible local program units
 
 @end table
 
+@node Specifying a set of metrics to compute
+@subsection Specifying a set of metrics to compute
+
+@noindent
+By default all the metrics are computed and reported. The switches
+described in this subsection allow you to control, on an individual
+basis, whether metrics are computed and
+reported. If at least one positive metric
+switch is specified (that is, a switch that defines that a given
+metric or set of metrics is to be computed), then only
+explicitly specified metrics are reported.
+
+@menu
+* Line Metrics Control::
+* Syntax Metrics Control::
+* Complexity Metrics Control::
+@end menu
+
 @node Line Metrics Control
-@subsection Line Metrics Control
+@subsubsection Line Metrics Control
 @cindex Line metrics control in @command{gnatmetric}
 
 @noindent
@@ -16436,54 +16458,93 @@ the number of comment lines
 the number of code lines containing end-of-line comments;
 
 @item
-the ratio between the number of lines that contain comments and the number of all
-the non-blank lines expressed in percentages (the comment percentage);
+the comment percentage: the ratio between the number of lines that contain
+comments and the number of all non-blank lines, expressed as a percentage;
 
 @item
 the number of empty lines and lines containing only space characters and/or
 format effectors (blank lines)
 
+@item
+the average number of code lines in subprogram bodies, task bodies, entry
+bodies and statement sequences in package bodies (this metric is only computed
+across the whole set of the analyzed units)
+
 @end itemize
 
-If @command{gnatmetric} is invoked on more than one source file, it sums the
-values of the line metrics for all the files being processed and then
-generates the cumulative results.
+@noindent
+@command{gnatmetric} sums the values of the line metrics for all the
+files being processed and then generates the cumulative results. The tool
+also computes for all the files being processed the average number of code
+lines in bodies.
 
-By default, all the line metrics are computed and reported. You can use the
-following switches to select the specific line metrics to be computed and
-reported (if any of these parameters is set, only explicitly specified line
-metrics are computed).
+You can use the following switches to select the specific line metrics
+to be computed and reported.
 
 @table @option
-@cindex @option{^-la^/LINES_ALL^} (@command{gnatmetric})
-@item ^-la^/LINES_ALL^
-The number of all lines
+@cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric})
 
-@cindex @option{^-lcode^/CODE_LINES^} (@command{gnatmetric})
-@item ^-lcode^/CODE_LINES^
-The number of code lines
+@ifclear vms
+@cindex @option{--no-lines@var{x}}
+@end ifclear
+
+@item ^--lines-all^/LINE_COUNT_METRICS=ALL_ON^
+Report all the line metrics
+
+@item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^
+Do not report any of line metrics
+
+@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^
+Report the number of all lines
+
+@item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^
+Do not report the number of all lines
+
+@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^
+Report the number of code lines
+
+@item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^
+Do not report the number of code lines
 
-@cindex @option{^-lcomm^/COMMENT_LINES^} (@command{gnatmetric})
-@item ^-lcomm^/COMENT_LINES^
-The number of comment lines
+@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^
+Report the number of comment lines
 
-@cindex @option{^-leol^/MIXED_CODE_COMMENTS^} (@command{gnatmetric})
-@item ^-leol^/MIXED_CODE_COMMENTS^
-The number of code lines containing
+@item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^
+Do not report the number of comment lines
+
+@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^
+Report the number of code lines containing
+end-of-line comments
+
+@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^
+Do not report the number of code lines containing
 end-of-line comments
 
-@cindex @option{^-ratio^/COMMENT_PERCENTAGE^} (@command{gnatmetric})
-@item ^-ratio^/COMMENT_PERCENTAGE^
-The comment percentage in the program text
+@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^
+Report the comment percentage in the program text
+
+@item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^
+Do not report the comment percentage in the program text
 
-@cindex @option{^-lb^/BLANK_LINES^} (@command{gnatmetric})
-@item ^-lb^/BLANK_LINES^
-The number of blank lines
+@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^
+Report the number of blank lines
+
+@item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^
+Do not report the number of blank lines
+
+@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^
+Report the average number of code lines in subprogram bodies, task bodies,
+entry bodies and statement sequences in package bodies. The metric is computed
+and reported for the whole set of processed Ada sources only.
+
+@item ^--no-lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_OFF^
+Do not report the average number of code lines in subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
 
 @end table
 
 @node Syntax Metrics Control
-@subsection Syntax Metrics Control
+@subsubsection Syntax Metrics Control
 @cindex Syntax metrics control in @command{gnatmetric}
 
 @noindent
@@ -16515,7 +16576,7 @@ the following metrics:
 @item Public subprograms
 This metric is computed for package specifications. It is the
 number of subprograms and generic subprograms declared in the visible
-part (including in nested packages, protected objects, and
+part (including the visible part of nested packages, protected objects, and
 protected types).
 
 @item All subprograms
@@ -16531,8 +16592,8 @@ subprograms are counted in the same way as ``usual'' subprogram bodies.
 This metric is computed for package specifications and
 generic package declarations. It is the total number of types
 that can be referenced from outside this compilation unit, plus the
-number of types from all the visible parts of all the visible generic packages.
-Generic formal types are not counted.  Only types, not subtypes,
+number of types from all the visible parts of all the visible generic
+packages. Generic formal types are not counted.  Only types, not subtypes,
 are included.
 
 @noindent
@@ -16571,52 +16632,80 @@ private etc.); the total number of types is computed and reported.
 
 @noindent
 By default, all the syntax metrics are computed and reported. You can use the
-following switches to select specific syntax metrics;
-if any of these is set, only the explicitly specified metrics are computed.
+following switches to select specific syntax metrics.
 
 @table @option
-@cindex @option{^-ed^/DECLARATION_TOTAL^} (@command{gnatmetric})
-@item ^-ed^/DECLARATION_TOTAL^
-The total number of declarations
 
-@cindex @option{^-es^/STATEMENT_TOTAL^} (@command{gnatmetric})
-@item ^-es^/STATEMENT_TOTAL^
-The total number of statements
+@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
 
-@cindex @option{^-eps^/^} (@command{gnatmetric})
-@item ^-eps^/INT_SUBPROGRAMS^
-The number of public subprograms in a compilation unit
+@ifclear vms
+@cindex @option{--no-syntax@var{x}}
+@end ifclear
+
+@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
+Report all the syntax metrics
+
+@item ^--no-syntax-all^/ALL_OFF^
+Do not report any of syntax metrics
+
+@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^
+Report the total number of declarations
+
+@item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^
+Do not report the total number of declarations
+
+@item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^
+Report the total number of statements
+
+@item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^
+Do not report the total number of statements
+
+@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^
+Report the number of public subprograms in a compilation unit
 
-@cindex @option{^-eas^/SUBPROGRAMS_ALL^} (@command{gnatmetric})
-@item ^-eas^/SUBPROGRAMS_ALL^
-The number of all the subprograms in a compilation unit
+@item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^
+Do not report the number of public subprograms in a compilation unit
 
-@cindex @option{^-ept^/INT_TYPES^} (@command{gnatmetric})
-@item ^-ept^/INT_TYPES^
-The number of public types in a compilation unit
+@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^
+Report the number of all the subprograms in a compilation unit
 
-@cindex @option{^-eat^/TYPES_ALL^} (@command{gnatmetric})
-@item ^-eat^/TYPES_ALL^
-The number of all the types in a compilation unit
+@item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^
+Do not report the number of all the subprograms in a compilation unit
 
-@cindex @option{^-enu^/PROGRAM_NESTING_MAX^} (@command{gnatmetric})
-@item ^-enu^/PROGRAM_NESTING_MAX^
-The maximal program unit nesting level
+@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^
+Report the number of public types in a compilation unit
 
-@cindex @option{^-ec^/CONSTRUCT_NESTING_MAX^} (@command{gnatmetric})
-@item ^-ec^/CONSTRUCT_NESTING_MAX^
-The maximal construct nesting level
+@item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^
+Do not report the number of public types in a compilation unit
+
+@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^
+Report the number of all the types in a compilation unit
+
+@item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^
+Do not report the number of all the types in a compilation unit
+
+@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^
+Report the maximal program unit nesting level
+
+@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
+Do not report the maximal program unit nesting level
+
+@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_ON^
+Report the maximal construct nesting level
+
+@item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^
+Do not report the maximal construct nesting level
 
 @end table
 
 @node Complexity Metrics Control
-@subsection Complexity Metrics Control
+@subsubsection Complexity Metrics Control
 @cindex Complexity metrics control in @command{gnatmetric}
 
 @noindent
 For a program unit that is an executable body (a subprogram body (including
 generic bodies), task body, entry body or a package body containing
-its own statement sequence ) @command{gnatmetric} computes the following
+its own statement sequence) @command{gnatmetric} computes the following
 complexity metrics:
 
 @itemize @bullet
@@ -16657,22 +16746,52 @@ When computing cyclomatic and essential complexity, @command{gnatmetric} skips
 the code in the exception handlers and in all the nested program units.
 
 By default, all the complexity metrics are computed and reported.
-For more finely-grained control you can use
+For more fine-grained control you can use
 the following switches:
 
 @table @option
-@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
+@cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric})
 
-@item ^-nocc^/SUPPRESS=CYCLOMATIC_COMPLEXITY^
-Do not compute the McCabe Cyclomatic Complexity
+@ifclear vms
+@cindex @option{--no-complexity@var{x}}
+@end ifclear
+
+@item ^--complexity-all^/COMPLEXITY_METRICS=ALL_ON^
+Report all the complexity metrics
+
+@item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^
+Do not report any of complexity metrics
+
+@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^
+Report the McCabe Cyclomatic Complexity
 
-@item ^-noec^/SUPPRESS=ESSENTIAL_COMPLEXITY^
-Do not compute the Essential Complexity
+@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^
+Do not report the McCabe Cyclomatic Complexity
 
-@item ^-nonl^/SUPPRESS=MAXIMAL_LOOP_NESTING^
-Do not compute maximal loop nesting level
+@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^
+Report the Essential Complexity
 
-@item ^-ne^/SUPPRESS=EXITS_AS_GOTOS^
+@item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^
+Do not report the Essential Complexity
+
+@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
+Report maximal loop nesting level
+
+@item ^--no-loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_OFF^
+Do not report maximal loop nesting level
+
+@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^
+Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
+The metric is computed and reported for whole set of processed Ada sources
+only.
+
+@item ^--no-complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_OFF^
+Do not report the average McCabe Cyclomatic Complexity for all the subprogram
+bodies, task bodies, entry bodies and statement sequences in package bodies
+
+@cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric})
+@item ^-ne^/NO_EXITS_AS_GOTOS^
 Do not consider @code{exit} statements as @code{goto}s when
 computing Essential Complexity
 
@@ -16688,7 +16807,7 @@ Additional @command{gnatmetric} switches are as follows:
 @item ^-files @var{filename}^/FILES=@var{filename}^
 @cindex @option{^-files^/FILES^} (@code{gnatmetric})
 Take the argument source files from the specified file. This file should be an
-ordinary textual file containing file names separated by spaces or
+ordinary text file containing file names separated by spaces or
 line breaks. You can use this switch more then once in the same call to
 @command{gnatmetric}. You also can combine this switch with
 an explicit list of files.
@@ -16713,18 +16832,22 @@ Quiet mode.
 @node Generate project-wide metrics
 @subsection Generate project-wide metrics
 
-In order to compute metrics on all units of a given project, one can use
+In order to compute metrics on all units of a given project, you can use
 the @command{gnat} driver along with the @option{-P} option:
 @smallexample
    gnat metric -Pproj
 @end smallexample
-If the project @code{proj} depends upon other projects, one can compute
+
+@noindent
+If the project @code{proj} depends upon other projects, you can compute
 the metrics on the project closure using the @option{-U} option:
 @smallexample
    gnat metric -Pproj -U
 @end smallexample
+
+@noindent
 Finally, if not all the units are relevant to a particular main
-program in the project closure, one can generate metrics for the set
+program in the project closure, you can generate metrics for the set
 of units needed to create a given main program (unit closure) using
 the @option{-U} option followed by the name of the main unit:
 @smallexample