Merge branch 'topic/documentation/compiler_rules_limitations' into 'master'

Enhance documentation about compiler-based rules limitations

Closes #478

See merge request eng/libadalang/langkit-query-language!441

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/gnatcheck_rm/using_gnatcheck.rst

@@ -874,8 +874,8 @@ activated.
 .. attention::
 
   Please not that for now it isn't possible to provide an exempted name which
-  designates an instance of a compiler-based rule (``Warnings``,
-  ``Style_Checks`` and ``Restrictions``).
+  designates an instance of a compiler-based rule (:ref:`Warnings`,
+  :ref:`Style_Checks` and :ref:`Restrictions`) with a custom name.
 
 A source code section where an exemption is active for a given rule is
 delimited by an ``exempt_on`` and ``exempt_off`` annotation pair:

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.