* [Ada] Fix inconsistent documentation for gnatmetric
@ 2019-07-11 8:04 Pierre-Marie de Rodat
0 siblings, 0 replies; only message in thread
From: Pierre-Marie de Rodat @ 2019-07-11 8:04 UTC (permalink / raw)
To: gcc-patches; +Cc: Bob Duff
[-- Attachment #1: Type: text/plain, Size: 388 bytes --]
One part said all metrics are enabled by default (which is now true),
and another part said the coupling metrics are disabled by default
(which is no longer true).
Tested on x86_64-pc-linux-gnu, committed on trunk
2019-07-11 Bob Duff <duff@adacore.com>
gcc/ada/
* doc/gnat_ugn/gnat_utility_programs.rst: Fix inconsistent
documentation for gnatmetric.
* gnat_ugn.texi: Regenerate.
[-- Attachment #2: patch.diff --]
[-- Type: text/x-diff, Size: 14605 bytes --]
--- gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
@@ -1214,7 +1214,7 @@ The following switches are available:
:samp:`f`
By default, gnathtml will generate html links only for global entities
- ('with'ed units, global variables and types,...). If you specify
+ ('with'ed units, global variables and types,...). If you specify
:switch:`-f` on the command line, then links will be generated for local
entities too.
@@ -1310,7 +1310,7 @@ Alternatively, you may run the script using the following command line:
``gnat2xml`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
+ the project-related switches). The project file package that can specify
``gnat2xml`` switches is named ``gnat2xml``.
.. _Switches_for_``gnat2xml``:
@@ -1780,7 +1780,7 @@ Alternatively, you may run the script using the following command line:
``gnatcheck`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
+ the project-related switches). The project file package that can specify
``gnatcheck`` switches is named ``Check``.
For full details, plese refer to :title:`GNATcheck Reference Manual`.
@@ -1804,11 +1804,11 @@ Alternatively, you may run the script using the following command line:
for computing various program metrics.
It takes an Ada source file as input and generates a file containing the
metrics data as output. Various switches control which
- metrics are computed and output.
+ metrics are reported.
``gnatmetric`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
+ the project-related switches). The project file package that can specify
``gnatmetric`` switches is named ``Metrics``.
The ``gnatmetric`` command has the form
@@ -1921,9 +1921,9 @@ Alternatively, you may run the script using the following command line:
.. index:: --short-file-names (gnatmetric)
:switch:`--short-file-names`
- Use 'short' source file names in the output. (The ``gnatmetric``
+ Use 'short' source file names in the output. (The ``gnatmetric``
output includes the name(s) of the Ada source file(s) from which the
- metrics are computed. By default each name includes the absolute
+ metrics are computed. By default each name includes the absolute
path. The :switch:`--short-file-names` switch causes ``gnatmetric``
to exclude all directory information from the file names that are
output.)
@@ -1980,12 +1980,11 @@ Alternatively, you may run the script using the following command line:
Specifying a set of metrics to compute
--------------------------------------
- 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.
+ By default all the metrics are reported. The switches described in this
+ subsection allow you to control, on an individual basis, whether metrics are
+ 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.
.. _Line_Metrics_Control:
@@ -2023,7 +2022,7 @@ Alternatively, you may run the script using the following command line:
code lines in bodies.
You can use the following switches to select the specific line metrics
- to be computed and reported.
+ to be reported.
.. index:: --lines (gnatmetric)
@@ -2089,10 +2088,9 @@ Alternatively, you may run the script using the following command line:
:switch:`--lines-average`
- 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.
+ Report the average number of code lines in subprogram bodies, task bodies,
+ entry bodies and statement sequences in package bodies. The metric is
+ reported for the whole set of processed Ada sources only.
:switch:`--no-lines-average`
@@ -2173,7 +2171,7 @@ Alternatively, you may run the script using the following command line:
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
+ packages. Generic formal types are not counted. Only types, not
subtypes, are included.
Along with the total number of public types, the following
@@ -2193,14 +2191,14 @@ Alternatively, you may run the script using the following command line:
* *All types*
This metric is computed for any compilation unit. It is equal to
the total number of the declarations of different types given in
- the compilation unit. The private and the corresponding full type
+ the compilation unit. The private and the corresponding full type
declaration are counted as one type declaration. Incomplete type
declarations and generic formal types are not counted.
No distinction is made among different kinds of types (abstract,
- private etc.); the total number of types is computed and reported.
+ private etc.); the total number of types is reported.
- By default, all the syntax metrics are computed and reported. You can
- use the following switches to select specific syntax metrics.
+ By default, all the syntax metrics are reported. You can use the following
+ switches to select specific syntax metrics.
.. index:: --syntax (gnatmetric)
@@ -2311,7 +2309,7 @@ Alternatively, you may run the script using the following command line:
According to McCabe, both control statements and short-circuit control
forms should be taken into account when computing cyclomatic
- complexity. For Ada 2012 we have also take into account conditional
+ complexity. For Ada 2012 we have also take into account conditional
expressions and quantified expressions. For each body, we compute
three metric values:
@@ -2364,9 +2362,8 @@ Alternatively, you may run the script using the following command line:
code of assertions and predicates (that is, subprogram preconditions and
postconditions, subtype predicates and type invariants) is also skipped.
- By default, all the complexity metrics are computed and reported.
- For more fine-grained control you can use
- the following switches:
+ By default, all the complexity metrics are reported. For more fine-grained
+ control you can use the following switches:
.. index:: --complexity (gnatmetric)
@@ -2408,8 +2405,7 @@ Alternatively, you may run the script using the following command line:
:switch:`--complexity-average`
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.
+ The metric is reported for whole set of processed Ada sources only.
:switch:`--no-complexity-average`
@@ -2623,8 +2619,8 @@ Alternatively, you may run the script using the following command line:
by invoking ``gnatmetric`` with the corresponding project file
and with the :switch:`-U` option.
- By default, all the coupling metrics are disabled. You can use the following
- switches to specify the coupling metrics to be computed and reported:
+ By default, all the coupling metrics are reported. You can use the following
+ switches to select specific syntax metrics.
.. index:: --tagged-coupling (gnatmetric)
.. index:: --hierarchy-coupling (gnatmetric)
@@ -2854,14 +2850,14 @@ Alternatively, you may run the script using the following command line:
of ``gnatpp``, which replaces the ASIS-based version.
The ``gnatpp`` tool is a utility for source reformatting / pretty
- printing. It takes an Ada source file as input and generates a
- reformatted version as output. You can specify various style
+ printing. It takes an Ada source file as input and generates a
+ reformatted version as output. You can specify various style
directives via switches; e.g., identifier case conventions, rules of
indentation, and comment layout.
``gnatpp`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
+ the project-related switches). The project file package that can specify
``gnatpp`` switches is named ``Pretty_Printer``.
``gnatpp`` cannot process sources that contain preprocessing
@@ -3019,7 +3015,7 @@ Alternatively, you may run the script using the following command line:
.. index:: --enum-upper-case (gnatpp)
:switch:`--enum-upper-case`
- Enumeration literals are in upper case. Overrides -n casing
+ Enumeration literals are in upper case. Overrides -n casing
setting.
.. index:: --enum-lower-case (gnatpp)
@@ -3133,7 +3129,7 @@ Alternatively, you may run the script using the following command line:
compatible.
This group of ``gnatpp`` switches controls the layout of comments and
- complex syntactic constructs. See :ref:`Formatting_Comments` for details
+ complex syntactic constructs. See :ref:`Formatting_Comments` for details
on their effect.
@@ -3750,10 +3746,10 @@ Alternatively, you may run the script using the following command line:
the same line.
A whole-line comment is indented according to the surrounding code,
- with some exceptions. Comments that start in column 1 are kept
- there. If possible, comments are not moved so far to the right that
- the maximum line length is exceeded. The ``--comments-unchanged``
- option turns off comment formatting. Special-form comments such as
+ with some exceptions. Comments that start in column 1 are kept
+ there. If possible, comments are not moved so far to the right that
+ the maximum line length is exceeded. The ``--comments-unchanged``
+ option turns off comment formatting. Special-form comments such as
SPARK-style ``--#...`` are left alone.
For an end-of-line comment, ``gnatpp`` tries to leave the same
@@ -3778,7 +3774,7 @@ Alternatively, you may run the script using the following command line:
are formatted according to the ``--comments-gnat-beginning`` and
``--comments-fill`` switches; other formatting switches are ignored. For
example, ``--comments-only --comments-fill`` means to fill comment
- paragraphs, and do nothing else. Likewise, ``--comments-only
+ paragraphs, and do nothing else. Likewise, ``--comments-only
--comments-gnat-beginning`` ensures comments start with at least two
spaces after ``--``, and ``--comments-only --comments-gnat-beginning
--comments-fill`` does both. If ``--comments-only`` is given without
@@ -3795,11 +3791,11 @@ Alternatively, you may run the script using the following command line:
the same casing as the corresponding defining identifier.
You control the casing for defining occurrences via the ``--name...``
- switches. With ``--name-case-as-declared``, which is the default,
+ switches. With ``--name-case-as-declared``, which is the default,
defining occurrences appear exactly as in the source file where they
- are declared. The other values for this switch --
+ are declared. The other values for this switch --
``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
- -- result in upper, lower, or mixed case, respectively. If
+ -- result in upper, lower, or mixed case, respectively. If
``gnatpp`` changes the casing of a defining occurrence, it
analogously changes the casing of all the usage occurrences of this
name.
@@ -3807,7 +3803,7 @@ Alternatively, you may run the script using the following command line:
If the defining occurrence of a name is not in the source compilation
unit currently being processed by ``gnatpp``, the casing of each
reference to this name is changed according to the switch (subject to
- the dictionary file mechanism described below). Thus ``gnatpp`` acts
+ the dictionary file mechanism described below). Thus ``gnatpp`` acts
as though the switch had affected the casing for the defining
occurrence of the name.
@@ -3844,7 +3840,7 @@ Alternatively, you may run the script using the following command line:
``-n`` switch or explicit dictionary files. For
example, by default the names ``Ada.Text_IO`` and
``GNAT.OS_Lib`` will appear as just shown, even in the presence of
- a ``--name-upper-case`` switch. To ensure that even
+ a ``--name-upper-case`` switch. To ensure that even
such names are rendered in uppercase, additionally supply the
--dictionary=- switch (or else place these names
in upper case in a dictionary file).
@@ -4754,7 +4750,7 @@ Alternatively, you may run the script using the following command line:
:switch:`--subdir={dirname}`
Test packages are placed in a subdirectory of the corresponding source
directory, with the name ``dirname``. Thus, each set of unit tests is located
- in a subdirectory of the code under test. If the sources are in separate
+ in a subdirectory of the code under test. If the sources are in separate
directories, each source directory has a test subdirectory named ``dirname``.
--- gcc/ada/gnat_ugn.texi
+++ gcc/ada/gnat_ugn.texi
@@ -19024,7 +19024,7 @@ If you do not specify an extension, it will default to @code{htm}.
@item @code{f}
By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
+('with'ed units, global variables and types,...). If you specify
@code{-f} on the command line, then links will be generated for local
entities too.
@end table
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2019-07-11 8:03 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-11 8:04 [Ada] Fix inconsistent documentation for gnatmetric Pierre-Marie de Rodat
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).