From 039f5fbd853e83c3156e4a6954d0993b574298e7 Mon Sep 17 00:00:00 2001
From: Andreas Dangel <andreas.dangel@pmd-code.org>
Date: Tue, 5 Sep 2023 19:53:21 +0200
Subject: [PATCH] [doc] Improve language docs

---
 docs/_includes/language_info.html      |  1 +
 docs/pages/pmd/languages/apex.md       | 20 +++++++++++++-------
 docs/pages/pmd/languages/coco.md       |  9 +++++----
 docs/pages/pmd/languages/cpp.md        |  3 ++-
 docs/pages/pmd/languages/cs.md         |  3 ++-
 docs/pages/pmd/languages/dart.md       |  5 +++--
 docs/pages/pmd/languages/fortran.md    |  3 ++-
 docs/pages/pmd/languages/gherkin.md    |  7 ++++---
 docs/pages/pmd/languages/go.md         |  7 +++++--
 docs/pages/pmd/languages/groovy.md     |  9 +++++++--
 docs/pages/pmd/languages/js_ts.md      |  2 +-
 docs/pages/pmd/languages/julia.md      |  2 +-
 docs/pages/pmd/languages/matlab.md     |  2 +-
 docs/pages/pmd/languages/objectivec.md |  2 +-
 docs/pages/pmd/languages/perl.md       |  2 +-
 docs/pages/pmd/languages/python.md     |  2 +-
 docs/pages/pmd/languages/scala.md      |  2 +-
 docs/pages/pmd/languages/swift.md      |  2 +-
 18 files changed, 52 insertions(+), 31 deletions(-)

diff --git a/docs/_includes/language_info.html b/docs/_includes/language_info.html
index ac7fa20ff2..3b47eba14c 100644
--- a/docs/_includes/language_info.html
+++ b/docs/_includes/language_info.html
@@ -2,6 +2,7 @@
     <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>
diff --git a/docs/pages/pmd/languages/apex.md b/docs/pages/pmd/languages/apex.md
index 5f32a7aee6..0349e27a2e 100644
--- a/docs/pages/pmd/languages/apex.md
+++ b/docs/pages/pmd/languages/apex.md
@@ -7,7 +7,12 @@ tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 summary: "Apex-specific features and guidance"
 ---
 
-{% include language_info.html name='Apex' id='apex' implementation='apex::lang.apex.ApexLanguageModule' supports_pmd=true supports_cpd=true %}
+> Apex 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.
+
+More info: [Apex Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_dev_guide.htm)
+
+{% include language_info.html name='Apex' id='apex' implementation='apex::lang.apex.ApexLanguageModule' supports_pmd=true supports_cpd=true since='5.5.0' %}
 
 ## Metrics framework
 
@@ -16,10 +21,10 @@ together with {% jdoc core::lang.metrics.MetricsUtil %}.
 
 ## Multifile Analysis
 
-See {% jdoc apex::lang.apex.multifile.ApexMultifileAnalysis %}
-Uses [ApexLink](https://github.com/nawforce/apex-link), see also [Apexlink POC #2830](https://github.com/pmd/pmd/pull/2830).
+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).
 
-Note: ApexLink new home: https://github.com/apex-dev-tools 
+{% include note.html content="ApexLink's new home: <https://github.com/apex-dev-tools>" %}
 
 Used for rule {% rule apex/design/UnusedMethod %}
 
@@ -29,7 +34,8 @@ See [Apex language properties](pmd_languages_configuration.html#apex-language-pr
 
 ## Parser
 
-We use Jorje...
-
-## Limitations
+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)).
diff --git a/docs/pages/pmd/languages/coco.md b/docs/pages/pmd/languages/coco.md
index 86a2c47dae..322404cb2c 100644
--- a/docs/pages/pmd/languages/coco.md
+++ b/docs/pages/pmd/languages/coco.md
@@ -1,14 +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"
 ---
 
-{% include language_info.html name='Coco' id='coco' implementation='coco::lang.coco.CocoLanguageModule' supports_cpd=true %}
-
 Coco is a modern programming language designed specifically for building event-driven software.
-It is part of the Coco Platform from <https://cocotec.io/>. 
+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.
diff --git a/docs/pages/pmd/languages/cpp.md b/docs/pages/pmd/languages/cpp.md
index aae5e70922..674e608ffe 100644
--- a/docs/pages/pmd/languages/cpp.md
+++ b/docs/pages/pmd/languages/cpp.md
@@ -1,8 +1,9 @@
 ---
-title: C/C++ 
+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 %}
diff --git a/docs/pages/pmd/languages/cs.md b/docs/pages/pmd/languages/cs.md
index 119c0cab51..94623f3554 100644
--- a/docs/pages/pmd/languages/cs.md
+++ b/docs/pages/pmd/languages/cs.md
@@ -1,8 +1,9 @@
 ---
-title: C#
+title: C# support
 permalink: pmd_languages_cs.html
 last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
+summary: "C# features and guidance"
 ---
 
 {% include language_info.html name='C#' id='cs' implementation='cs::lang.cs.CsLanguageModule' supports_cpd=true %}
diff --git a/docs/pages/pmd/languages/dart.md b/docs/pages/pmd/languages/dart.md
index bf2b89343f..7c2a3597e1 100644
--- a/docs/pages/pmd/languages/dart.md
+++ b/docs/pages/pmd/languages/dart.md
@@ -1,8 +1,9 @@
 ---
-title: Dart
+title: Dart support
 permalink: pmd_languages_dart.html
 last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
+summary: "Dart features and guidance"
 ---
 
-{% include language_info.html name='Dart' id='dart' implementation='dart::lang.dart.DartLanguageModule' supports_cpd=true %}
+{% include language_info.html name='Dart' id='dart' implementation='dart::lang.dart.DartLanguageModule' supports_cpd=true since='6.14.0' %}
diff --git a/docs/pages/pmd/languages/fortran.md b/docs/pages/pmd/languages/fortran.md
index 5cc6408002..49119ed390 100644
--- a/docs/pages/pmd/languages/fortran.md
+++ b/docs/pages/pmd/languages/fortran.md
@@ -1,8 +1,9 @@
 ---
-title: Fortran
+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 %}
diff --git a/docs/pages/pmd/languages/gherkin.md b/docs/pages/pmd/languages/gherkin.md
index 11f1afe3a0..9ffb2565ab 100644
--- a/docs/pages/pmd/languages/gherkin.md
+++ b/docs/pages/pmd/languages/gherkin.md
@@ -1,16 +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"
 ---
 
-{% include language_info.html name='Gherkin' id='gherkin' implementation='gherkin::lang.gherkin.GherkinLanguageModule' supports_cpd=true %}
-
 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.
 
diff --git a/docs/pages/pmd/languages/go.md b/docs/pages/pmd/languages/go.md
index 492c986a3a..aee65e06ab 100644
--- a/docs/pages/pmd/languages/go.md
+++ b/docs/pages/pmd/languages/go.md
@@ -1,8 +1,11 @@
 ---
-title: Go
+title: Go support
 permalink: pmd_languages_go.html
 last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
+summary: "Go features and guidance"
 ---
 
-{% include language_info.html name='Go' id='go' implementation='go::lang.go.GoLanguageModule' supports_cpd=true %}
+[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' %}
diff --git a/docs/pages/pmd/languages/groovy.md b/docs/pages/pmd/languages/groovy.md
index 4c4038b99a..95a7bba1b1 100644
--- a/docs/pages/pmd/languages/groovy.md
+++ b/docs/pages/pmd/languages/groovy.md
@@ -1,8 +1,13 @@
 ---
-title: Groovy
+title: Groovy support
 permalink: pmd_languages_groovy.html
 last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
+summary: "Groovy features and guidance"
 ---
 
-{% include language_info.html name='Groovy' id='groovy' implementation='groovy::lang.groovy.GroovyLanguageModule' supports_cpd=true %}
+[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' %}
diff --git a/docs/pages/pmd/languages/js_ts.md b/docs/pages/pmd/languages/js_ts.md
index 1634cd41e9..ed4ec61451 100644
--- a/docs/pages/pmd/languages/js_ts.md
+++ b/docs/pages/pmd/languages/js_ts.md
@@ -7,7 +7,7 @@ summary: "JavaScript and TypeScript infos"
 ---
 
 {% 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 %}
+{% include language_info.html name='TypeScript' id='ts' implementation='javascript::lang.typescript.TsLanguageModule' supports_cpd=true since='7.0.0' %}
 
 
 **JavaScript** support is using [Rhino](https://github.com/mozilla/rhino) for parsing and supports CPD as well as
diff --git a/docs/pages/pmd/languages/julia.md b/docs/pages/pmd/languages/julia.md
index dc8facd2c6..b941267661 100644
--- a/docs/pages/pmd/languages/julia.md
+++ b/docs/pages/pmd/languages/julia.md
@@ -5,7 +5,7 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Julia' id='julia' implementation='julia::lang.julia.JuliaLanguageModule' supports_cpd=true %}
+{% include language_info.html name='Julia' id='julia' implementation='julia::lang.julia.JuliaLanguageModule' supports_cpd=true since='7.0.0' %}
 
 The [Julia](https://julialang.org/) language is dynamically typed, like a scripting language,
 and has good support for interactive use. 
diff --git a/docs/pages/pmd/languages/matlab.md b/docs/pages/pmd/languages/matlab.md
index 623d53372d..c997c54a75 100644
--- a/docs/pages/pmd/languages/matlab.md
+++ b/docs/pages/pmd/languages/matlab.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Matlab' id='matlab' implementation='matlab::lang.matlab.MatlabLanguageModule' supports_cpd=true %}
+{% include language_info.html name='Matlab' id='matlab' implementation='matlab::lang.matlab.MatlabLanguageModule' supports_cpd=true since='5.3.0' %}
diff --git a/docs/pages/pmd/languages/objectivec.md b/docs/pages/pmd/languages/objectivec.md
index a1e18fcc1c..5823825f86 100644
--- a/docs/pages/pmd/languages/objectivec.md
+++ b/docs/pages/pmd/languages/objectivec.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='objectivec' id='objectivec' implementation='objectivec::lang.objectivec.ObjectiveCLanguageModule' supports_cpd=true %}
+{% include language_info.html name='objectivec' id='objectivec' implementation='objectivec::lang.objectivec.ObjectiveCLanguageModule' supports_cpd=true since='5.3.0' %}
diff --git a/docs/pages/pmd/languages/perl.md b/docs/pages/pmd/languages/perl.md
index e2fc04a58b..ebe19aeeb5 100644
--- a/docs/pages/pmd/languages/perl.md
+++ b/docs/pages/pmd/languages/perl.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Perl' id='perl' implementation='perl::lang.perl.PerlLanguageModule' supports_cpd=true %}
+{% include language_info.html name='Perl' id='perl' implementation='perl::lang.perl.PerlLanguageModule' supports_cpd=true since='5.5.0' %}
diff --git a/docs/pages/pmd/languages/python.md b/docs/pages/pmd/languages/python.md
index 3db917aa3b..080631a58c 100644
--- a/docs/pages/pmd/languages/python.md
+++ b/docs/pages/pmd/languages/python.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Python' id='python' implementation='python::lang.python.PythonLanguageModule' supports_cpd=true %}
+{% include language_info.html name='Python' id='python' implementation='python::lang.python.PythonLanguageModule' supports_cpd=true since='5.3.0' %}
diff --git a/docs/pages/pmd/languages/scala.md b/docs/pages/pmd/languages/scala.md
index 2dddf16d1b..07af33b654 100644
--- a/docs/pages/pmd/languages/scala.md
+++ b/docs/pages/pmd/languages/scala.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Scala' id='scala' implementation='scala::lang.scala.ScalaLanguageModule' supports_pmd=true supports_cpd=true %}
+{% include language_info.html name='Scala' id='scala' implementation='scala::lang.scala.ScalaLanguageModule' supports_pmd=true supports_cpd=true since='5.3.0' %}
diff --git a/docs/pages/pmd/languages/swift.md b/docs/pages/pmd/languages/swift.md
index 050ebe578b..fc5fa75022 100644
--- a/docs/pages/pmd/languages/swift.md
+++ b/docs/pages/pmd/languages/swift.md
@@ -5,4 +5,4 @@ last_updated: September 2023 (7.0.0)
 tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 ---
 
-{% include language_info.html name='Swift' id='swift' implementation='swift::lang.swift.SwiftLanguageModule' supports_pmd=true supports_cpd=true %}
+{% include language_info.html name='Swift' id='swift' implementation='swift::lang.swift.SwiftLanguageModule' supports_pmd=true supports_cpd=true since='5.3.7' %}