Merge branch 'topic/metric_n_doc' into 'master'

Rework the "Metrics Related" documentation to include the "N" parameter in every rule documentation Closes #358 See merge request eng/libadalang/langkit-query-language!316
AdaCore · Nov 28, 2024 · 81662f8 · 81662f8
2 parents af6f4b8 + 9bff594
commit 81662f8
Show file tree

Hide file tree

Showing 5 changed files with 56 additions and 66 deletions.
diff --git a/lkql_checker/doc/generated/predefined_rules.rst b/lkql_checker/doc/generated/predefined_rules.rst
@@ -7927,9 +7927,6 @@ LKQL rule options files:
 The rules in this section can be used to enforce compliance with
 specific code metrics, by checking that the metrics computed for a program
 lie within user-specifiable bounds.
-Depending on the metric, there may be a lower bound, an upper bound, or both.
-A construct is flagged if the value of the metric exceeds the upper bound
-or is less than the lower bound.
 
 The name of any metrics rule consists of the prefix ``Metrics_``
 followed by the name of the corresponding metric:
@@ -7939,25 +7936,6 @@ followed by the name of the corresponding metric:
 The meaning and the computed values of the metrics are
 the same as in *gnatmetric*.
 
-For the ``+R`` option, each metrics rule has a numeric parameter
-specifying the bound (integer or real, depending on a metric).
-
-*Example:* the rule
-
-::
-
-  +RMetrics_Cyclomatic_Complexity : 7
-
-
-means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
-
-To turn OFF the check for cyclomatic complexity metric,
-use the following option:
-
-::
-
-  -RMetrics_Cyclomatic_Complexity
-
 
 
 .. _Metrics_Cyclomatic_Complexity:
@@ -7970,8 +7948,12 @@ use the following option:
 The ``Metrics_Cyclomatic_Complexity`` rule takes a positive integer as
 upper bound.  A program unit that is an executable body exceeding this limit will be flagged.
 
-This rule has the following optional parameter for the ``+R`` option and for
-LKQL rule options files:
+This rule has the following parameters for the ``+R`` option and for LKQL rule
+options files:
+
+*N: int*
+   Maximum cyclomatic complexity a body can have without being flagged, all
+   bodies with a higher index will be flagged.
 
 *Exempt_Case_Statements: bool*
    Whether to count the complexity introduced by ``case`` statement or ``case``
@@ -8018,12 +8000,19 @@ of tests needed to satisfy paths coverage testing completeness criterion.
 
 .. index:: Metrics_Essential_Complexity
 
-The ``Metrics_Essential_Complexity`` rule takes a positive integer as
-upper bound.  A program unit that is an executable body exceeding this limit will be flagged.
+The ``Metrics_Essential_Complexity`` rule takes a positive integer as upper bound.
+A program unit that is an executable body exceeding this limit will be flagged.
 
 The Ada essential complexity metric is a McCabe cyclomatic complexity metric counted
 for the code that is reduced by excluding all the pure structural Ada control statements.
 
+This rule has the following (mandatory) parameter for the ``+R`` option and
+for LKQL rule options files:
+
+*N: int*
+   Maximum essential complexity a body can have without being flagged, all
+   bodies with a higher index will be flagged.
+
 .. rubric:: Example
 
 .. code-block:: ada
@@ -8057,17 +8046,23 @@ for the code that is reduced by excluding all the pure structural Ada control st
 
 .. index:: Metrics_LSLOC
 
-The ``Metrics_LSLOC`` rule takes a positive integer as
-upper bound.  A program unit declaration or a program unit body exceeding
-this limit will be flagged.
+The ``Metrics_LSLOC`` rule takes a positive integer as upper bound. A program
+unit declaration or a program unit body exceeding this limit will be flagged.
 
-The metric counts the total number of declarations and the total number of statements.
+The metric counts the total number of declarations and the total number of
+statements.
 
-This rule has the following optional parameter for the ``+R`` option and for
-LKQL rule options files:
+This rule has the following parameters for the ``+R`` option and for LKQL rule
+options files:
+
+*N: int*
+   Maximum number of logical source lines a program declaration / body can have
+   without being flagged, all bodies with a higher number of LSLOC will be
+   flagged.
 
 *Subprograms: bool*
-   Whether to check the rule for subprogram bodies only.
+   Optional parameter specifying whether to check the rule for subprogram
+   bodies only.
 
 .. rubric:: Example
 

diff --git a/lkql_checker/share/lkql/metrics_cyclomatic_complexity.lkql b/lkql_checker/share/lkql/metrics_cyclomatic_complexity.lkql
@@ -6,8 +6,12 @@ fun metrics_cyclomatic_complexity(unit, n : int = 5,
     |" The ``Metrics_Cyclomatic_Complexity`` rule takes a positive integer as
     |" upper bound.  A program unit that is an executable body exceeding this limit will be flagged.
     |"
-    |" This rule has the following optional parameter for the ``+R`` option and for
-    |" LKQL rule options files:
+    |" This rule has the following parameters for the ``+R`` option and for LKQL rule
+    |" options files:
+    |"
+    |" *N: int*
+    |"    Maximum cyclomatic complexity a body can have without being flagged, all
+    |"    bodies with a higher index will be flagged.
     |"
     |" *Exempt_Case_Statements: bool*
     |"    Whether to count the complexity introduced by ``case`` statement or ``case``

diff --git a/lkql_checker/share/lkql/metrics_essential_complexity.lkql b/lkql_checker/share/lkql/metrics_essential_complexity.lkql
@@ -2,12 +2,19 @@ import metrics
 
 @unit_check(help="essential complexity", execution_cost=3, category="Metrics")
 fun metrics_essential_complexity(unit, n : int = 3) =
-    |" The ``Metrics_Essential_Complexity`` rule takes a positive integer as
-    |" upper bound.  A program unit that is an executable body exceeding this limit will be flagged.
+    |" The ``Metrics_Essential_Complexity`` rule takes a positive integer as upper bound.
+    |" A program unit that is an executable body exceeding this limit will be flagged.
     |"
     |" The Ada essential complexity metric is a McCabe cyclomatic complexity metric counted
     |" for the code that is reduced by excluding all the pure structural Ada control statements.
     |"
+    |" This rule has the following (mandatory) parameter for the ``+R`` option and
+    |" for LKQL rule options files:
+    |"
+    |" *N: int*
+    |"    Maximum essential complexity a body can have without being flagged, all
+    |"    bodies with a higher index will be flagged.
+    |"
     |" .. rubric:: Example
     |"
     |" .. code-block:: ada

diff --git a/lkql_checker/share/lkql/metrics_lsloc.lkql b/lkql_checker/share/lkql/metrics_lsloc.lkql
@@ -3,17 +3,23 @@ import metrics
 @unit_check(help="Logical source lines", execution_cost=3,
             rule_name="Metrics_LSLOC", category="Metrics")
 fun metrics_lsloc(unit, n : int = 5, subprograms=false) =
-    |" The ``Metrics_LSLOC`` rule takes a positive integer as
-    |" upper bound.  A program unit declaration or a program unit body exceeding
-    |" this limit will be flagged.
+    |" The ``Metrics_LSLOC`` rule takes a positive integer as upper bound. A program
+    |" unit declaration or a program unit body exceeding this limit will be flagged.
     |"
-    |" The metric counts the total number of declarations and the total number of statements.
+    |" The metric counts the total number of declarations and the total number of
+    |" statements.
     |"
-    |" This rule has the following optional parameter for the ``+R`` option and for
-    |" LKQL rule options files:
+    |" This rule has the following parameters for the ``+R`` option and for LKQL rule
+    |" options files:
+    |"
+    |" *N: int*
+    |"    Maximum number of logical source lines a program declaration / body can have
+    |"    without being flagged, all bodies with a higher number of LSLOC will be
+    |"    flagged.
     |"
     |" *Subprograms: bool*
-    |"    Whether to check the rule for subprogram bodies only.
+    |"    Optional parameter specifying whether to check the rule for subprogram
+    |"    bodies only.
     |"
     |" .. rubric:: Example
     |"

diff --git a/lkql_jit/cli/src/main/java/com/adacore/lkql_jit/LKQLDocRules.java b/lkql_jit/cli/src/main/java/com/adacore/lkql_jit/LKQLDocRules.java
@@ -515,9 +515,6 @@ The rule identifier is used as a key for LKQL rule configuration objects (see
                 The rules in this section can be used to enforce compliance with
                 specific code metrics, by checking that the metrics computed for a program
                 lie within user-specifiable bounds.
-                Depending on the metric, there may be a lower bound, an upper bound, or both.
-                A construct is flagged if the value of the metric exceeds the upper bound
-                or is less than the lower bound.
 
                 The name of any metrics rule consists of the prefix ``Metrics_``
                 followed by the name of the corresponding metric:
@@ -526,25 +523,6 @@ The rule identifier is used as a key for LKQL rule configuration objects (see
                 (The 'LSLOC' acronym stands for 'Logical Source Lines Of Code'.)
                 The meaning and the computed values of the metrics are
                 the same as in *gnatmetric*.
-
-                For the ``+R`` option, each metrics rule has a numeric parameter
-                specifying the bound (integer or real, depending on a metric).
-
-                *Example:* the rule
-
-                ::
-
-                  +RMetrics_Cyclomatic_Complexity : 7
-
-
-                means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
-
-                To turn OFF the check for cyclomatic complexity metric,
-                use the following option:
-
-                ::
-
-                  -RMetrics_Cyclomatic_Complexity
                 """);
 
         printCategory(