[plsql] Document PMD Exclusions

docs/_data/sidebars/pmd_sidebar.yml

@@ -349,6 +349,9 @@ entries:
     - title: Apex code metrics
       url: /pmd_apex_metrics_index.html
       output: web, pdf
+    - title: PLSQL
+      url: /pmd_languages_plsql.html
+      output: web, pdf
   - title: Developer Documentation
     output: web, pdf
     folderitems:

docs/pages/pmd/languages/plsql.md

@@ -0,0 +1,49 @@
+---
+title: PLSQL
+permalink: pmd_languages_plsql.html
+last_updated: March 2021 (6.33.0)
+---
+
+## Parsing Exclusions
+
+The grammar for PLSQL used in PMD has several bugs and might not parse all DDL scripts
+without errors. However, it should be best practice to call PMD for _every_ DDL script.
+Thus, we introduce the following workaround to cope with the situation.
+
+We introduce two special comments `PMD-EXCLUDE-BEGIN` and `PMD-EXCLUDE-END`
+which cause PMD to treat the source in between these comments more or less
+like a multi-line comment, or in other words, just not try to parse them.
+
+It is good practice to include a reason for excluding inside the
+`-- PMD-EXCUDE-BEGIN` comment separated by a colon.
+
+The `PMD-EXCLUDE-BEGIN` and `PMD-EXLUDE-END` comment lines must not contain
+other statements, e.g. `do_xy(); -- PMD-EXCLUDE-BEGIN` is invalid.
+
+Example:
+
+```
+begin
+  do_something();
+  -- PMD-EXCLUDE-BEGIN: PMD does not like dbms_lob.trim (clash with TrimExpression)
+  dbms_lob.trim(the_blob, 1000);
+  -- PMD-EXCLUDE-END
+  do_something_else();
+end;
+```
+
+The existence of exclusions can be detected with the attributes
+`ExcludedRangesCount` and `ExcludedLinesCount` of the top-level ASTInput node.
+If nothing is excluded, both values are 0 (zero).
+Otherwise, `ExcludedRangesCount` contains the number of excluded line-ranges
+and `ExcludedLinesCount` is the total number of excluded lines.
+A future version of PMD might pass the line excluded line ranges,
+source fragments and the corresponding reason comments
+as child nodes of the top-level ASTInput node.
+
+In order to keep track where such parse exclusions are used, you could create
+a custom XPath rule with the following expression:
+
+    /Input[@ExcludedRangesCount > 0]
+
+This will find all files with at least one excluded range.

pmd-plsql/etc/grammar/PldocAST.jjt

@@ -4641,36 +4641,8 @@ Still, ~ 15% of perfectly valid DDL scripts could not be parsed by PMD.
 
 Nevertheless it should be best practice to call PMD for _every_ DDL script.
 
-Thus, we introduce the following workaround to cope with the situation.
-We introduce two special comments PMD-EXCLUDE-BEGIN and PMD-EXCLUDE-END
-which cause PMD to treat the source inbetween these comments more or less
-like a multi-line comment, or in other words, just not try to parse them.
-
-It is good practice to include a reason for excluding inside the
--- PMD-EXCUDE-BEGIN comment.
-
-The PMD-EXCLUDE-BEGIN and PMD-EXLUDE-END comment lines must not contain
-other statements, e.g. do_xy(); -- PMD-EXCLUDE-BEGIN is invalid.
-
-Example:
-
-begin
-  do_something();
-  -- PMD-EXCLUDE-BEGIN: PMD does not like dbms_lob.trim (clash with TrimExpression)
-  dbms_lob.trim(the_blob, 1000);
-  -- PMD-EXCLUDE-END
-  do_something_else();
-end;
-
-The existence of exclusions can be detected with the attributes
-excludedRangesCount and excludedLinesCount of the top-lvel ASTInput node.
-If nothing is excluded, both values are 0 (zero).
-Otherwise, excludedRangesCount contains the number of excluded line-ranges
-and excludedRangesCount is the total number of excluded lines.
-A future version of PMD might pass the line ecluded line ranges,
-source fragments and the corresponding reason comments
-as child nodes of the top-level ASTInput node.
-See the commented code in Input().
+See /docs/pages/languages/plsql.md for further explanations on how
+to use PMD-EXCLUDE-BEGIN and PMD-EXCLUDE-END.
 */
 
 /* COMMENTS */