Add documentation about compiler-based rule instantiation limitations

Author: HugoGGuerrier

lkql_checker/doc/generated/predefined_rules.rst

@@ -4316,6 +4316,21 @@ the pragma ``Restrictions`` or ``Restriction_Warnings``.
          Restrictions: {Arg: ["Max_Task_Entries=>2", "No_Access_Subprograms"]}
       }
 
+.. attention::
+   It is forbidden to provide the same restriction name in multiple instances
+   of the ``Restrictions`` rule. Meaning that such configuration is invalid and
+   will cause GNATcheck to issue an error message:
+
+   .. code-block:: lkql
+
+      val rules = @{
+         Restrictions: [
+            {Arg: ["Max_Task_Entries=>2", "No_Access_Subprograms"]},
+            {Arg: ["Max_Task_Entries=>6"], instance_name: "Another_Instance"}
+                  # ^^^^^^^^^^^^^^^^ The "Max_Task_Entries" name is provided in multiple instances of "Restrictions"
+         ]
+      }
+
 If your code contains pragmas ``Warnings`` with parameter ``Off``, this may
 result in false negatives for this rule, because the corresponding warnings
 generated during compilation will be suppressed. The workaround is to
@@ -5362,6 +5377,21 @@ mentioned above).
          Warnings: "u"
       }
 
+.. attention::
+   It is forbidden to provide the same parameter in multiple instance of the
+   ``Warnings`` rule. Meaning that such configuration is invalid and will cause
+   GNATcheck to issue an error message:
+
+   .. code-block:: lkql
+
+      val rules = @{
+         Warnings: [
+            {Arg: "u"},
+            {Arg: "u", instance_name: "Another_Instance"}
+                 # ^-- The "u" parameter is provided in multiple instances of "Warnings"
+         ]
+      }
+
 Note that ``s`` and ``e`` parameters, corresponding respectively to GNAT
 ``-gnatws`` and ``-gnatwe`` options, are not allowed for the ``Warnings``
 GNATcheck rule since they may have side effects on other rules.
@@ -6236,6 +6266,21 @@ the compiler style check that corresponds to ``-gnatyO`` style check option.
          Style_Checks: "xz"
       }
 
+.. attention::
+   It is forbidden to provide the same parameter in multiple instances of the
+   ``Style_Checks`` rule. Meaning that such configuration is invalid and will
+   cause GNATcheck to issue an error message:
+
+   .. code-block:: lkql
+
+      val rules = @{
+         Style_Checks: [
+            {Arg: "xz"},
+            {Arg: "x", instance_name: "Another_Instance"}
+                 # ^-- The "x" parameter is provided in multiple instances of "Style_Checks"
+         ]
+      }
+
 This rule allows parametric rule exemptions, the parameters
 that are allowed in the definition of exemption sections are the
 same as the parameters of the rule itself.

lkql_checker/doc/stubs/restrictions.lkql

@@ -32,6 +32,21 @@ fun restrictions() =
     |"          Restrictions: {Arg: ["Max_Task_Entries=>2", "No_Access_Subprograms"]}
     |"       }
     |"
+    |" .. attention::
+    |"    It is forbidden to provide the same restriction name in multiple instances
+    |"    of the ``Restrictions`` rule. Meaning that such configuration is invalid and
+    |"    will cause GNATcheck to issue an error message:
+    |"
+    |"    .. code-block:: lkql
+    |"
+    |"       val rules = @{
+    |"          Restrictions: [
+    |"             {Arg: ["Max_Task_Entries=>2", "No_Access_Subprograms"]},
+    |"             {Arg: ["Max_Task_Entries=>6"], instance_name: "Another_Instance"}
+    |"                   # ^^^^^^^^^^^^^^^^ The "Max_Task_Entries" name is provided in multiple instances of "Restrictions"
+    |"          ]
+    |"       }
+    |"
     |" If your code contains pragmas ``Warnings`` with parameter ``Off``, this may
     |" result in false negatives for this rule, because the corresponding warnings
     |" generated during compilation will be suppressed. The workaround is to

lkql_checker/doc/stubs/style_checks.lkql

@@ -42,6 +42,21 @@ fun style_checks() =
     |"          Style_Checks: "xz"
     |"       }
     |"
+    |" .. attention::
+    |"    It is forbidden to provide the same parameter in multiple instances of the
+    |"    ``Style_Checks`` rule. Meaning that such configuration is invalid and will
+    |"    cause GNATcheck to issue an error message:
+    |"
+    |"    .. code-block:: lkql
+    |"
+    |"       val rules = @{
+    |"          Style_Checks: [
+    |"             {Arg: "xz"},
+    |"             {Arg: "x", instance_name: "Another_Instance"}
+    |"                  # ^-- The "x" parameter is provided in multiple instances of "Style_Checks"
+    |"          ]
+    |"       }
+    |"
     |" This rule allows parametric rule exemptions, the parameters
     |" that are allowed in the definition of exemption sections are the
     |" same as the parameters of the rule itself.

lkql_checker/doc/stubs/warnings.lkql

@@ -34,6 +34,21 @@ fun warnings() =
     |"          Warnings: "u"
     |"       }
     |"
+    |" .. attention::
+    |"    It is forbidden to provide the same parameter in multiple instance of the
+    |"    ``Warnings`` rule. Meaning that such configuration is invalid and will cause
+    |"    GNATcheck to issue an error message:
+    |"
+    |"    .. code-block:: lkql
+    |"
+    |"       val rules = @{
+    |"          Warnings: [
+    |"             {Arg: "u"},
+    |"             {Arg: "u", instance_name: "Another_Instance"}
+    |"                  # ^-- The "u" parameter is provided in multiple instances of "Warnings"
+    |"          ]
+    |"       }
+    |"
     |" Note that ``s`` and ``e`` parameters, corresponding respectively to GNAT
     |" ``-gnatws`` and ``-gnatwe`` options, are not allowed for the ``Warnings``
     |" GNATcheck rule since they may have side effects on other rules.