From: Bob Duff Date: Thu, 11 Jul 2019 08:02:17 +0000 (+0000) Subject: [Ada] Fix inconsistent documentation for gnatmetric X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=4ae83b58d2316f22d6874b6901fa61fe0f823e3f;p=gcc.git [Ada] Fix inconsistent documentation for gnatmetric 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). 2019-07-11 Bob Duff gcc/ada/ * doc/gnat_ugn/gnat_utility_programs.rst: Fix inconsistent documentation for gnatmetric. * gnat_ugn.texi: Regenerate. From-SVN: r273391 --- diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog index 1b338d382b7..a39069c6f64 100644 --- a/gcc/ada/ChangeLog +++ b/gcc/ada/ChangeLog @@ -1,3 +1,9 @@ +2019-07-11 Bob Duff + + * doc/gnat_ugn/gnat_utility_programs.rst: Fix inconsistent + documentation for gnatmetric. + * gnat_ugn.texi: Regenerate. + 2019-07-11 Bob Duff * doc/gnat_ugn/gnat_utility_programs.rst: Document gnatpp's diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst index 5ad86dc9e16..fc39214e3e0 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst +++ b/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``. diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi index db2adafcc1a..29424e76155 100644 --- a/gcc/ada/gnat_ugn.texi +++ b/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