Merge branch 'master' into experimental-apex-parser

.all-contributorsrc

@@ -7268,6 +7268,34 @@
       "contributions": [
         "bug"
       ]
+    },
+    {
+      "login": "shai-bennathan",
+      "name": "Shai Bennathan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/62336907?v=4",
+      "profile": "https://github.com/shai-bennathan",
+      "contributions": [
+        "bug",
+        "code"
+      ]
+    },
+    {
+      "login": "ethauvin",
+      "name": "Erik C. Thauvin",
+      "avatar_url": "https://avatars.githubusercontent.com/u/705618?v=4",
+      "profile": "https://erik.thauvin.net/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "ciufudean",
+      "name": "ciufudean",
+      "avatar_url": "https://avatars.githubusercontent.com/u/19208954?v=4",
+      "profile": "https://github.com/ciufudean",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/workflows/build.yml

@@ -32,7 +32,7 @@ jobs:
         os: [ ubuntu-latest, windows-latest, macos-latest ]
     if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 2
     - uses: actions/cache@v3

.github/workflows/git-repo-sync.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: false
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 100
     - name: Setup Environment

.github/workflows/troubleshooting.yml

@@ -15,7 +15,7 @@ jobs:
         os: [ ubuntu-latest ]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/cache@v3
         with:
           path: |

docs/_data/sidebars/pmd_sidebar.yml

@@ -124,6 +124,9 @@ entries:
         - title: PMD Java API
           output: web, pdf
           url: /pmd_userdocs_tools_java_api.html
+        - title: bld PMD Extension
+          output: web, pdf
+          url: /pmd_userdocs_tools_bld.html
         - title: CI integrations
           output: web, pdf
           url: /pmd_userdocs_tools_ci.html
@@ -313,7 +316,7 @@ entries:
     - title: null
       output: web, pdf
       subfolders:
-      - title: Salesforce VisualForce Rules
+      - title: Salesforce Visualforce Rules
         output: web, pdf
         subfolderitems:
         - title: Index
@@ -349,7 +352,7 @@ entries:
     - title: null
       output: web, pdf
       subfolders:
-      - title: VM Rules
+      - title: Velocity Template Language (VTL) Rules
         output: web, pdf
         subfolderitems:
         - title: Index
@@ -382,6 +385,9 @@ entries:
         - title: Index
           output: web, pdf
           url: /pmd_rules_xml.html
+        - title: Best Practices
+          output: web, pdf
+          url: /pmd_rules_xml_bestpractices.html
         - title: Error Prone
           output: web, pdf
           url: /pmd_rules_xml_errorprone.html
@@ -403,12 +409,41 @@ entries:
   - title: Language-Specific Documentation
     output: web, pdf
     folderitems:
+    - title: Overview
+      url: /pmd_languages_index.html
+      output: web, pdf
     - title: Language configuration
       url: /pmd_languages_configuration.html
       output: web, pdf
     - title: Apex
       url: /pmd_languages_apex.html
       output: web, pdf
+    - title: C/C++
+      url: /pmd_languages_cpp.html
+      output: web, pdf
+    - title: C#
+      url: /pmd_languages_cs.html
+      output: web, pdf
+    - title: Coco
+      url: /pmd_languages_coco.html
+      output: web, pdf
+    - title: Dart
+      url: /pmd_languages_dart.html
+      output: web, pdf
+    - title: Fortran
+      url: /pmd_languages_fortran.html
+      output: web, pdf
+    - title: Gherkin
+      url: /pmd_languages_gherkin.html
+      output: web, pdf
+    - title: Go
+      url: /pmd_languages_go.html
+      output: web, pdf
+    - title: Groovy
+      url: /pmd_languages_groovy.html
+    - title: HTML
+      url: /pmd_languages_html.html
+      output: web, pdf
     - title: Java
       url: /pmd_languages_java.html
       output: web, pdf
@@ -418,30 +453,57 @@ entries:
     - title: JSP
       url: /pmd_languages_jsp.html
       output: web, pdf
+    - title: Julia
+      url: /pmd_languages_julia.html
+      output: web, pdf
     - title: Kotlin
       url: /pmd_languages_kotlin.html
       output: web, pdf
+    - title: Lua
+      url: /pmd_languages_lua.html
+      output: web, pdf
+    - title: Matlab
+      url: /pmd_languages_matlab.html
+      output: web, pdf
+    - title: Modelica
+      url: /pmd_languages_modelica.html
+      output: web, pdf
+    - title: Objective-C
+      url: /pmd_languages_objectivec.html
+      output: web, pdf
+    - title: Perl
+      url: /pmd_languages_perl.html
+      output: web, pdf
+    - title: PHP
+      url: /pmd_languages_php.html
+      output: web, pdf
     - title: PLSQL
       url: /pmd_languages_plsql.html
       output: web, pdf
+    - title: Python
+      url: /pmd_languages_python.html
+      output: web, pdf
+    - title: Ruby
+      url: /pmd_languages_ruby.html
+      output: web, pdf
+    - title: Scala
+      url: /pmd_languages_scala.html
+      output: web, pdf
+    - title: Swift
+      url: /pmd_languages_swift.html
+      output: web, pdf
+    - title: T-SQL
+      url: /pmd_languages_tsql.html
+      output: web, pdf
     - title: Visualforce
       url: /pmd_languages_visualforce.html
       output: web, pdf
+    - title: Velocity Template Language (VTL)
+      url: /pmd_languages_vm.html
+      output: web, pdf
     - title: XML and XML dialects
       url: /pmd_languages_xml.html
       output: web, pdf
-    - title: HTML
-      url: /pmd_languages_html.html
-      output: web, pdf
-    - title: Gherkin
-      url: /pmd_languages_gherkin.html
-      output: web, pdf
-    - title: Julia
-      url: /pmd_languages_julia.html
-      output: web, pdf
-    - title: Coco
-      url: /pmd_languages_coco.html
-      output: web, pdf
   - title: Developer Documentation
     output: web, pdf
     folderitems:
@@ -493,6 +555,9 @@ entries:
         - title: Creating (XML) dump of the AST
           url: /pmd_devdocs_experimental_ast_dump.html
           output: web, pdf
+        - title: List of experimental Features
+          url: /tag_experimental.html
+          output: web, pdf
   - title: Project documentation
     output: web, pdf
     folderitems:

docs/_data/tags.yml

@@ -10,3 +10,6 @@ allowed-tags:
   - tools           # About tools and integrations, Maven, gradle, etc.
   - devdocs         # About PMD internals, contributing, building, projects
   - languages       # Language-specific documentation pages
+  - PmdCapableLanguage
+  - CpdCapableLanguage
+  - experimental

docs/_includes/language_info.html

@@ -0,0 +1,12 @@
+<details class="language-info">
+    <summary>Language Info for {{include.name}}</summary>
+    <div class="card">
+        <ul class="list-group list-group-flush">
+            {% if include.since %}<li class="list-group-item">Since PMD {{include.since}}</li>{% endif %}
+            <li class="list-group-item">Implementation: {% jdoc include.implementation %}</li>
+            <li class="list-group-item">Id: {{include.id}}</li>
+            <li class="list-group-item">PMD: {% if include.supports_pmd %}✔️{% else %}❌{% endif %}</li>
+            <li class="list-group-item">CPD: {% if include.supports_cpd %}✔️{% else %}❌{% endif %}</li>
+        </ul>
+    </div>
+</details>

docs/_plugins/javadoc_tag.rb

@@ -106,16 +106,25 @@ class JavadocTag < Liquid::Tag
   def initialize(tag_name, doc_ref, tokens)
     super
 
-    # sanitize a little
-    doc_ref.delete! " \"'"
+    @doc_ref = doc_ref
+  end
 
-    arr = doc_ref.split("#") # split into fqcn + member suffix
+  def render(var_ctx)
+    # maybe the parameter is actually a variable - try to resolve it first
+    if var_ctx.key?(@doc_ref)
+        @doc_ref = var_ctx[@doc_ref]
+    end
+
+    # sanitize a little
+    @doc_ref.delete! " \"'"
+
+    arr = @doc_ref.split("#") # split into fqcn + member suffix
 
     @type_fqcn = arr[0]
     @member_suffix = arr[1] || "" # default to empty string
 
     unless Regexp.new('(!\w*!)?' + Regexp.union(JDocNamespaceDeclaration::NAMESPACED_FQCN_REGEX, JDocNamespaceDeclaration::SYM_REGEX).source ) =~ @type_fqcn
-      fail "Wrong syntax for type reference, expected eg nspace::a.b.C, !opts!nspace::a.b.C, or :nspace"
+      fail "Wrong syntax for type reference, expected eg nspace::a.b.C, !opts!nspace::a.b.C, or :nspace, but got \'" + @type_fqcn + "\'"
     end
 
     # If no options, then split produces [@type_fqcn]
@@ -130,14 +139,11 @@ class JavadocTag < Liquid::Tag
     elsif tag_name == "jdoc_old"
       @use_previous_api_version = true
     end
-  end
-
-  def render(var_ctx)
 
     artifact_name, @type_fqcn = JDocNamespaceDeclaration::parse_fqcn(@type_fqcn, var_ctx)
     resolved_type = JavadocTag::fqcn_type(artifact_name, @type_fqcn)
 
-    JavadocTag::diagnose(artifact_name, @type_fqcn, @is_package_ref, resolved_type)
+    diagnose(var_ctx, artifact_name, @type_fqcn, @is_package_ref, resolved_type)
 
     # Expand FQCN of arguments
     @member_suffix.gsub!(JDocNamespaceDeclaration::NAMESPACED_FQCN_REGEX) {|fqcn| JDocNamespaceDeclaration::parse_fqcn(fqcn, var_ctx)[1]}
@@ -215,15 +221,18 @@ class JavadocTag < Liquid::Tag
 
   BASE_PMD_DIR = File.join(File.expand_path(File.dirname(__FILE__)), "..", "..")
 
-  def self.diagnose(artifact_id, fqcn, expect_package, resolved_type)
+  def diagnose(context, artifact_id, fqcn, expect_package, resolved_type)
     tag_name= expect_package ? "jdoc_package" : "jdoc"
+    # Note: the line numbers don't account for the frontmatter lines
+    # See https://github.com/jekyll/jekyll/issues/7192 and https://github.com/jekyll/jekyll/pull/9385
+    location = "#{context['page']['path']}:#{@line_number}+?"
 
     if resolved_type == :package && !expect_package
-      warn "\e[33;1m#{tag_name} generated link to #{fqcn}, but it was found to be a package name. Did you mean to use jdoc_package instead of jdoc?\e[0m"
+      warn "\e[33;1m#{location}: #{tag_name} generated link to #{fqcn}, but it was found to be a package name. Did you mean to use jdoc_package instead of jdoc?\e[0m"
     elsif resolved_type == :file && expect_package
-      warn "\e[33;1m#{tag_name} generated link to #{fqcn}, but it was found to be a java file name. Did you mean to use jdoc instead of jdoc_package?\e[0m"
+      warn "\e[33;1m#{location}: #{tag_name} generated link to #{fqcn}, but it was found to be a java file name. Did you mean to use jdoc instead of jdoc_package?\e[0m"
     elsif !resolved_type
-      warn "\e[33;1m#{tag_name} generated link to #{fqcn}, but the #{expect_package ? "directory" : "source file"} couldn't be found in the source tree of #{artifact_id}\e[0m"
+      warn "\e[33;1m#{location}: #{tag_name} generated link to #{fqcn}, but the #{expect_package ? "directory" : "source file"} couldn't be found in the source tree of #{artifact_id}\e[0m"
     end
   end
 

docs/_plugins/jdoc_namespace_tag.rb

@@ -99,10 +99,11 @@ class JDocNamespaceDeclaration < Liquid::Tag
   private
 
   JDOC_NAMESPACE_MAP = "jdoc_nspaces"
-  RESERVED_NSPACES = ['ant', 'apex', 'cli', 'core', 'cpp', 'cs', 'dart', 'dist', 'doc', 'fortran', 'go', 'groovy', 'java',
-    'javascript', 'jsp',
+  RESERVED_NSPACES = ['ant', 'apex', 'cli', 'coco', 'core', 'cpp', 'cs', 'dart', 'dist', 'doc',
+    'fortran', 'gherkin', 'go', 'groovy', 'html', 'java',
+    'javascript', 'jsp', 'julia',
     'kotlin', 'lang-test', 'lua', 'matlab', 'objectivec', 'perl', 'php', 'plsql', 'python', 'ruby', 'scala', 'swift',
-    'test', 'test-schema', 'ui',
+    'test', 'test-schema', 'tsql', 'ui',
     'modelica', 'visualforce', 'vm', 'xml'].flat_map {|m| [m, "pmd-" + m]}
 
   def self.make_base_namespaces

docs/css/customstyles.css

@@ -1008,8 +1008,11 @@ span.soft {
 }
 
 @media (min-height: 600px) and (min-width: 990px) {
+    /* sticky sidebar for big screens */
     #mysidebar {
         position: fixed !important;
+        overflow: scroll;
+        height: 80%;
     }
 }
 
@@ -1268,3 +1271,7 @@ h4.panel-title {
 a.edit-header {
     font-size: 15px;
 }
+
+.language-info {
+    margin: 2em;
+}

docs/css/theme-green.css

@@ -87,3 +87,10 @@ li.sidebarTitle {
     margin-bottom:2.5px;
     margin-left:5px;
 }
+
+blockquote {
+    border-left: 5px solid #01c172;
+    padding: 10px 0 10px 1rem;
+    margin: 1rem 0;
+    font-style: italic;
+}

docs/index.md

@@ -39,7 +39,8 @@ used as a quality gate, to enforce a coding standard for your codebase. Among ot
 things, PMD can be run:
 * As a [Maven goal](pmd_userdocs_tools_maven.html)
 * As an [Ant task](pmd_userdocs_tools_ant.html)
-* As a [Gradle task](https://docs.gradle.org/current/userguide/pmd_plugin.html)
+* As a [Gradle task](pmd_userdocs_tools_gradle.html)
+* As a [bld operation](pmd_userdocs_tools_bld.html)
 * From [command-line](pmd_userdocs_installation.html#running-pmd-via-command-line)
 
 **CPD**, the **copy-paste detector**, is also distributed with PMD. You can also use it

docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md

@@ -142,7 +142,9 @@ definitely don't come for free. It is much effort and requires perseverance to i
 *   For a minimal implementation, it just needs to return a parser *(see step #6)*.
 *   It can be used to provide other features for your language like
     *   violation suppression logic
-    *   violation decorators, to add additional language specific information to the created violations
+    *   {% jdoc core::reporting::ViolationDecorator %}s, to add additional language specific information to the
+        created violations. The [Java language module](pmd_languages_java.html#violation-decorators) uses this to
+        provide the method name or class name, where the violation occurred.
     *   metrics
     *   custom XPath functions
 
@@ -228,3 +230,25 @@ definitely don't come for free. It is much effort and requires perseverance to i
     This will load all rulesets and verify, that all required attributes are provided.
 
     *Note:* You'll need to add your ruleset to `categories.properties`, so that it can be found.
+
+### 15. Create documentation page
+Finishing up your new language module by adding a page in the documentation. Create a new markdown file
+`<langId>.md` in `docs/pages/pmd/languages/`. This file should have the following frontmatter:
+
+```
+---
+title: <Language Name>
+permalink: pmd_languages_<langId>.html
+last_updated: <Month> <Year> (<PMD Version>)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
+---
+```
+
+On this page, language specifics can be documented, e.g. when the language was first supported by PMD.
+There is also the following Jekyll Include, that creates summary box for the language:
+
+```
+{% raw %}
+{% include language_info.html name='<Language Name>' id='<langId>' implementation='<langId>::lang.<langId>.<langId>LanguageModule' supports_cpd=true supports_pmd=true %}
+{% endraw %}
+```

docs/pages/pmd/devdocs/major_contributions/adding_a_new_javacc_based_language.md

@@ -81,7 +81,9 @@ definitely don't come for free. It is much effort and requires perseverance to i
 *   For a minimal implementation, it just needs to return a parser *(see step #5)*.
 *   It can be used to provide other features for your language like
     *   violation suppression logic
-    *   violation decorators, to add additional language specific information to the created violations
+    *   {% jdoc core::reporting::ViolationDecorator %}s, to add additional language specific information to the
+        created violations. The [Java language module](pmd_languages_java.html#violation-decorators) uses this to
+        provide the method name or class name, where the violation occurred.
     *   metrics (see below "Optional features")
     *   custom XPath functions
 *   See `VmHandler` class as an example
@@ -181,6 +183,29 @@ The Scala module also has a test, written in Kotlin instead of Java:
 
     *Note:* You'll need to add your category ruleset to `categories.properties`, so that it can be found.
 
+### 13. Create documentation page
+Finishing up your new language module by adding a page in the documentation. Create a new markdown file
+`<langId>.md` in `docs/pages/pmd/languages/`. This file should have the following frontmatter:
+
+```
+---
+title: <Language Name>
+permalink: pmd_languages_<langId>.html
+last_updated: <Month> <Year> (<PMD Version>)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
+---
+```
+
+On this page, language specifics can be documented, e.g. when the language was first supported by PMD.
+There is also the following Jekyll Include, that creates summary box for the language:
+
+```
+{% raw %}
+{% include language_info.html name='<Language Name>' id='<langId>' implementation='<langId>::lang.<langId>.<langId>LanguageModule' supports_cpd=true supports_pmd=true %}
+{% endraw %}
+```
+
+
 ## Debugging with Rule Designer
 
 When implementing your grammar it may be very useful to see how PMD parses your example files.

docs/pages/pmd/devdocs/major_contributions/adding_new_cpd_language.md

@@ -79,6 +79,27 @@ If your language only supports CPD, then you can subclass {% jdoc core::lang.imp
 
 5. Add some tests for your tokenizer by following the [section below](#testing-your-implementation).
 
+6. Finishing up your new language module by adding a page in the documentation. Create a new markdown file
+   `<langId>.md` in `docs/pages/pmd/languages/`. This file should have the following frontmatter:
+
+   ```
+   ---
+   title: <Language Name>
+   permalink: pmd_languages_<langId>.html
+   last_updated: <Month> <Year> (<PMD Version>)
+   tags: [languages, CpdCapableLanguage]
+   ---
+   ```
+
+   On this page, language specifics can be documented, e.g. when the language was first supported by PMD.
+   There is also the following Jekyll Include, that creates summary box for the language:
+
+   ```
+   {% raw %}
+   {% include language_info.html name='<Language Name>' id='<langId>' implementation='<langId>::lang.<langId>.<langId>LanguageModule' supports_cpd=true %}
+   {% endraw %}
+   ```
+
 ### Declaring tokenizer options
 
 To make the tokenizer configurable, first define some property descriptors using

docs/pages/pmd/languages/apex.md

@@ -1,15 +1,40 @@
 ---
 title: Apex support
 permalink: pmd_languages_apex.html
+last_updated: September 2023 (7.0.0)
 author: Clément Fournier
-last_updated: March 2021 (7.0.0)
-tags: [languages]
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 summary: "Apex-specific features and guidance"
 ---
 
-{% include warning.html content="Todo for pmd 7" %}
+> [Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_dev_guide.htm) is a strongly
+> typed, object-oriented programming language that allows developers to execute flow and
+> transaction control statements on the Salesforce Platform server, in conjunction with calls to the API.
 
-### Metrics framework
+{% include language_info.html name='Apex' id='apex' implementation='apex::lang.apex.ApexLanguageModule' supports_pmd=true supports_cpd=true since='5.5.0' %}
 
-In order to use code metrics in Java, use the metrics constants in {% jdoc apex::lang.apex.metrics.ApexMetrics %},
+## Metrics framework
+
+In order to use code metrics in Apex, use the metrics constants in {% jdoc apex::lang.apex.metrics.ApexMetrics %},
 together with {% jdoc core::lang.metrics.MetricsUtil %}.
+
+## Multifile Analysis
+
+Integration happens in {% jdoc apex::lang.apex.multifile.ApexMultifileAnalysis %}. It uses
+[ApexLink](https://github.com/nawforce/apex-link). For detailed information, see also [Apexlink POC #2830](https://github.com/pmd/pmd/pull/2830).
+
+{% include note.html content="ApexLink's new home: <https://github.com/apex-dev-tools>" %}
+
+Used for rule {% rule apex/design/UnusedMethod %}
+
+## Language Properties
+
+See [Apex language properties](pmd_languages_configuration.html#apex-language-properties)
+
+## Parser
+
+We use Jorje, the Apex parsers that is shipped within the Apex Language Server. This is part of
+the [Salesforce Extensions for VS Code](https://github.com/forcedotcom/salesforcedx-vscode).
+
+We take the binary from <https://github.com/forcedotcom/salesforcedx-vscode/tree/develop/packages/salesforcedx-vscode-apex/out>
+and provide it as a maven dependency (see [pmd-apex-jorje](https://github.com/pmd/pmd/tree/master/pmd-apex-jorje)).

docs/pages/pmd/languages/coco.md

@@ -1,10 +1,15 @@
 ---
-title: Coco 
+title: Coco support 
 permalink: pmd_languages_coco.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Coco features and guidance"
 ---
 
-Coco is a modern programming language designed specifically for building event-driven software.
-It is part of the Coco Platform from <https://cocotec.io/>. 
+> Coco is a modern programming language designed specifically for building event-driven software.
+> It is part of the Coco Platform from <https://cocotec.io/>.
+
+{% include language_info.html name='Coco' id='coco' implementation='coco::lang.coco.CocoLanguageModule' supports_cpd=true since='7.0.0' %}
 
 ## Support in PMD
 Starting from version 7.0.0, Coco support was added to CPD.

docs/pages/pmd/languages/cpp.md

@@ -0,0 +1,13 @@
+---
+title: C/C++ support
+permalink: pmd_languages_cpp.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "C/C++ features and guidance"
+---
+
+{% include language_info.html name='C++' id='cpp' implementation='cpp::lang.cpp.CppLanguageModule' supports_cpd=true since='3.5' %}
+
+## Language Properties
+
+See [Cpp language properties](pmd_languages_configuration.html#cpp-language-properties)

docs/pages/pmd/languages/cs.md

@@ -0,0 +1,9 @@
+---
+title: C# support
+permalink: pmd_languages_cs.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "C#-specific features and guidance"
+---
+
+{% include language_info.html name='C#' id='cs' implementation='cs::lang.cs.CsLanguageModule' supports_cpd=true since='4.3' %}

docs/pages/pmd/languages/dart.md

@@ -0,0 +1,11 @@
+---
+title: Dart support
+permalink: pmd_languages_dart.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Dart-specific features and guidance"
+---
+
+> [Dart](https://dart.dev/) is a client-optimized language for fast apps on any platform.
+
+{% include language_info.html name='Dart' id='dart' implementation='dart::lang.dart.DartLanguageModule' supports_cpd=true since='6.14.0' %}

docs/pages/pmd/languages/fortran.md

@@ -0,0 +1,9 @@
+---
+title: Fortran support
+permalink: pmd_languages_fortran.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Fortran features and guidance"
+---
+
+{% include language_info.html name='Fortran' id='fortran' implementation='fortran::lang.fortran.FortranLanguageModule' supports_cpd=true %}

docs/pages/pmd/languages/gherkin.md

@@ -1,12 +1,17 @@
 ---
-title: Gherkin 
+title: Gherkin support
 permalink: pmd_languages_gherkin.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Gherkin features and guidance"
 ---
 
 The [Gherkin](https://cucumber.io/docs/gherkin/) language is used to define test cases for the
 [Cucumber](https://cucumber.io/) testing tool for behavior-driven development.
 The Gherkin syntax is designed to be non-technical, making it human-readable for a wide audience.
 
+{% include language_info.html name='Gherkin' id='gherkin' implementation='gherkin::lang.gherkin.GherkinLanguageModule' supports_cpd=true since='6.48.0' %}
+
 ## Support in PMD
 Starting from version 6.48.0, Gherkin support was added to CPD.
 

docs/pages/pmd/languages/go.md

@@ -0,0 +1,11 @@
+---
+title: Go support
+permalink: pmd_languages_go.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Go features and guidance"
+---
+
+> [Go](https://golang.org/) is a statically typed, compiled high-level programming language.
+
+{% include language_info.html name='Go' id='go' implementation='go::lang.go.GoLanguageModule' supports_cpd=true since='5.2.0' %}

docs/pages/pmd/languages/groovy.md

@@ -0,0 +1,13 @@
+---
+title: Groovy support
+permalink: pmd_languages_groovy.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: "Groovy-specific features and guidance"
+---
+
+> [Apache Groovy](https://groovy-lang.org/) is a powerful, optionally typed and dynamic language, with static-typing and
+> static compilation capabilities, for the Java platform aimed at improving developer productivity thanks to a concise,
+> familiar and easy to learn syntax.
+
+{% include language_info.html name='Groovy' id='groovy' implementation='groovy::lang.groovy.GroovyLanguageModule' supports_cpd=true since='5.5.2' %}

docs/pages/pmd/languages/html.md

@@ -1,24 +1,20 @@
 ---
-title: Processing HTML files
+title: HTML support
 permalink: pmd_languages_html.html
-last_updated: April 2022 (6.45.0)
+last_updated: September 2023 (7.0.0)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage, experimental]
+summary: "HTML-specific features and guidance"
 ---
 
-## The HTML language module
-
-**Since:** 6.45.0
-
-**Minimum Java Runtime:** Java 8
+{% include language_info.html name='HTML' id='html' implementation='html::lang.html.HtmlLanguageModule' supports_pmd=true supports_cpd=true since='6.45.0' %}
 
 {% include warning.html content="This language module is experimental and may change any time." %}
 
 The HTML language module uses [jsoup](https://jsoup.org/) for parsing.
 
-XPath 2.0 rules are supported, but the DOM is not always a typical XML/XPath DOM.
+XPath rules are supported, but the DOM is not always a typical XML/XPath DOM.
 In the Designer, text nodes appear as nodes with name "#text", but they can
 be selected as usual using `text()`.
 
-XML Namespaces are not supported. The local name of attributes include the prefix,
+XML Namespaces are not supported. The local name of attributes includes the prefix,
 so that you have to select attributes by e.g. `//*[@*[local-name() = 'if:true']]`.
-
-Only XPath 1.0 rules are not supported.

docs/pages/pmd/languages/index.md

@@ -0,0 +1,9 @@
+---
+title: Overview
+permalink: pmd_languages_index.html
+last_updated: September 2023 (7.0.0)
+tags: [languages]
+---
+
+* [PmdCapableLanguages](tag_PmdCapableLanguage.html)
+* [CpdCapableLanguages](tag_CpdCapableLanguage.html)

docs/pages/pmd/languages/java.md

@@ -2,11 +2,13 @@
 title: Java support
 permalink: pmd_languages_java.html
 author: Clément Fournier
-last_updated: August 2023 (7.0.0)
-tags: [languages]
+last_updated: September 2023 (7.0.0)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 summary: "Java-specific features and guidance"
 ---
 
+{% include language_info.html name='Java' id='java' implementation='java::lang.java.JavaLanguageModule' supports_pmd=true supports_cpd=true since='1.0.0' %}
+
 {% include warning.html content="WIP, todo for pmd 7" %}
 
 ## Overview of supported Java language versions
@@ -47,6 +49,10 @@ it via the environment variable `PMD_JAVA_OPTS` and select the new language vers
 
 Note: we only support preview language features for the latest two java versions.
 
+## Language Properties
+
+See [Java language properties](pmd_languages_configuration.html#java-language-properties)
+
 ## Type and symbol resolution
 
 Java being a statically typed language, a Java program contains more information that just its syntax tree; for instance, every expression has a static type, and every method call is bound to a method overload statically (even if that overload is virtual). In PMD, much of this information is resolved from the AST by additional passes, which run after parsing, and before rules can inspect the tree. 
@@ -62,7 +68,7 @@ TODO describe
 
 ## Type and symbol APIs
 
-TODO describe APIs 
+TODO describe APIs: see #4319 and #2689
 
 ## Metrics framework
 
@@ -83,3 +89,15 @@ public Object visit(ASTMethodDeclaration node, Object data) {
 ```
 
 The Javadocs are the reference documentation.
+
+## Violation Decorators
+
+Violations reported are the same for all languages, but languages can opt in to provide more details.
+Java does this by adding the following additional information for each reported violation:
+
+* {% jdoc core::RuleViolation#VARIABLE_NAME %}
+* {% jdoc core::RuleViolation#METHOD_NAME %}
+* {% jdoc core::RuleViolation#CLASS_NAME %}
+* {% jdoc core::RuleViolation#PACKAGE_NAME %}
+
+You can access these via {% jdoc core::RuleViolation#getAdditionalInfo() %}

docs/pages/pmd/languages/js_ts.md

@@ -1,15 +1,22 @@
 ---
-title: JavaScript and TypeScript
+title: JavaScript and TypeScript support
 permalink: pmd_languages_js_ts.html
-tags: [languages]
-summary: "JavaScript and TypeScript infos"
+last_updated: September 2023 (7.0.0)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
+summary: "JavaScript- and TypeScript-specific features and guidance"
 ---
 
+{% include language_info.html name='JavaScript' id='ecmascript' implementation='javascript::lang.ecmascript.EcmascriptLanguageModule' supports_pmd=true supports_cpd=true %}
+{% include language_info.html name='TypeScript' id='ts' implementation='javascript::lang.typescript.TsLanguageModule' supports_cpd=true since='7.0.0' %}
+
+## JavaScript
+
 **JavaScript** support is using [Rhino](https://github.com/mozilla/rhino) for parsing and supports CPD as well as
 PMD with rules.
 
 See [Compatibility Table](https://mozilla.github.io/rhino/compat/engines.html) for supported language features.
 
+## TypeScript
 
 **TypeScript** is supported for Copy-Paste-Detection only and uses the ANTLR grammar from
 [antlr/grammars-v4](https://github.com/antlr/grammars-v4/tree/master/javascript/typescript).

docs/pages/pmd/languages/jsp.md

@@ -1,11 +1,14 @@
 ---
 title: JSP Support
 permalink: pmd_languages_jsp.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 author: Pieter Vanraemdonck
-tags: [languages]
 summary: "JSP-specific features and guidance"
 ---
 
+{% include language_info.html name='Java Server Pages' id='jsp' implementation='jsp::lang.jsp.JspLanguageModule' supports_pmd=true supports_cpd=true %}
+
 ## What is currently supported and what is not
 
 In short, JSP files that are XHTML-compliant, are supported.
@@ -38,16 +41,3 @@ The XHTML support means that:
     further broken down. If you want to create rules that check the code
     inside EL expressions or JSP scriptlets (a.o.), you currently would
     have to do "manual" string manipulation (e.g. using regular expressions).
-
-## How to use it
-
-Using the command-line interface, two new options can be used in the arguments string:
-
-*   "-jsp" : this triggers checking JSP files (they are not checked by default)
-*   "-nojava" : this tells PMD not to check java source files (they are checked by default)
-
-Using the Ant task, you decide if PMD must check JSP files by choosing
-what files are given to the PMD task. If you use a fileset that
-contains only ".java" files, JSP files obviously will not be checked.
-
-If you want to call the PMD API for checking JSP files, you should investigate the javadoc of PMD.

docs/pages/pmd/languages/julia.md

@@ -1,15 +1,20 @@
 ---
-title: Julia 
+title: Julia support
 permalink: pmd_languages_julia.html
+last_updated: September 2023 (7.0.0)
+tags: [languages, CpdCapableLanguage]
+summary: Julia-specific features and guidance
 ---
 
-The [Julia](https://julialang.org/) is dynamically typed, like a scripting language,
-and has good support for interactive use. 
-Julia was designed from the beginning for high performance.
-Julia programs compile to efficient native code for multiple platforms via LLVM.
+> The [Julia](https://julialang.org/) language is dynamically typed, like a scripting language,
+> and has good support for interactive use.
+> Julia was designed from the beginning for high performance.
+> Julia programs compile to efficient native code for multiple platforms via LLVM.
+
+{% include language_info.html name='Julia' id='julia' implementation='julia::lang.julia.JuliaLanguageModule' supports_cpd=true since='7.0.0' %}
 
 ## Support in PMD
 Starting from version 7.0.0, Julia support was added to CPD.
 
-### Limitations
+## Limitations
 - Support for Julia only extends to CPD to detect code duplication in Julia source files.