[doc] Review links in release notes and doc pages

- fix javadoc to find Kotlin files - fix formatting for language info box - fix tocmaker link generator
2024-03-10 20:21:01 +01:00 · 2024-03-10 20:21:01 +01:00 · eb631b987d
commit eb631b987d
parent d1ef7c728c
18 changed files with 437 additions and 414 deletions
--- a/docs/_includes/language_info.html
+++ b/docs/_includes/language_info.html
@ -1,12 +1,14 @@
 <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>
+<summary markdown="span">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>
--- a/docs/_plugins/javadoc_tag.rb
+++ b/docs/_plugins/javadoc_tag.rb
@ -107,6 +107,9 @@ class JavadocTag < Liquid::Tag
    super

    @doc_ref = doc_ref
+    # in case the doc_ref is a variable (like in %include usage), remember the original value
+    # so that we can restore it after we resolved the variable
+    @initial_doc_ref = doc_ref
  end

  def render(var_ctx)
@ -143,7 +146,8 @@ class JavadocTag < Liquid::Tag
    artifact_name, @type_fqcn = JDocNamespaceDeclaration::parse_fqcn(@type_fqcn, var_ctx)
    resolved_type = JavadocTag::fqcn_type(artifact_name, @type_fqcn)

-    diagnose(var_ctx, artifact_name, @type_fqcn, @is_package_ref, resolved_type)
+    # don't warn for unresolved reference when pointing to old api
+    diagnose(var_ctx, artifact_name, @type_fqcn, @is_package_ref, resolved_type) unless @use_previous_api_version

    # Expand FQCN of arguments
    @member_suffix.gsub!(JDocNamespaceDeclaration::NAMESPACED_FQCN_REGEX) {|fqcn| JDocNamespaceDeclaration::parse_fqcn(fqcn, var_ctx)[1]}
@ -161,6 +165,11 @@ class JavadocTag < Liquid::Tag
    api_version = var_ctx["site.pmd." + (@use_previous_api_version ? "previous_version" : "version")]

    link_url = doclink(var_ctx["site.javadoc_url_prefix"], artifact_name, api_version, @type_fqcn, @member_suffix, resolved_type)
+
+    # reset the doc_ref, if we resolved a variable reference
+    @doc_ref = @initial_doc_ref
+
+    # return the markup
    markup_link(visible_name, link_url)
  end

@ -248,15 +257,24 @@ class JavadocTag < Liquid::Tag

    src_dirs = [
        File.join(artifact_dir, "src", "main", "java"),
+        File.join(artifact_dir, "src", "main", "kotlin"),
        File.join(artifact_dir, "target", "generated-sources", "javacc"),
        File.join(artifact_dir, "target", "generated-sources", "antlr4")
    ].select {|dir| File.exist?(dir)}

    targets = src_dirs
                  .map {|dir| File.join(dir, fqcn.split("."))}
-                  .map {|f| File.file?(f + ".java") ? :file : File.exist?(f) ? :package : nil}
+                  .map do |f|
+                    if File.file?(f + ".java") || File.file?(f + ".kt")
+                        next :file
+                    end
+                    if File.exist?(f)
+                        next :package
+                    end
+                    next nil
+                   end

-    # consider nested classes (one level is only supported...)
+    # consider nested classes (one level is only supported... and only java...)
    nested_targets = src_dirs
                        .map { |dir| File.join(dir, fqcn.split(".")[0..-2]) }
                        .map {|f| File.file?(f + ".java") ? :nested : File.exist?(f) ? :package : nil}
--- a/docs/_plugins/tocmaker_block.rb
+++ b/docs/_plugins/tocmaker_block.rb
@ -18,7 +18,7 @@ class TocMakerBlock < Liquid::Block
  end

  def to_internal_link(header)
-    url = header.downcase.gsub(/\s+/, "-").gsub(/[:\(\)]+/, "")
+    url = header.downcase.gsub(/[^a-zA-Z0-9 -]+/, "").strip.gsub(/\s+/, "-")

    "[#{header}](##{url})"
  end
--- a/docs/css/customstyles.css
+++ b/docs/css/customstyles.css
@ -1175,10 +1175,6 @@ a code {
    color: #248ec2;
 }

-code + a > code {
-    margin-left: -7px;
-}
-
 table th code {
    color: white;
 }
--- a/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md
+++ b/docs/pages/pmd/devdocs/major_contributions/adding_a_new_antlr_based_language.md
@ -144,7 +144,7 @@ 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
-    *   {% jdoc core::reporting::ViolationDecorator %}s, to add additional language specific information to the
+    *   {% 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
--- a/docs/pages/pmd/devdocs/major_contributions/adding_a_new_javacc_based_language.md
+++ b/docs/pages/pmd/devdocs/major_contributions/adding_a_new_javacc_based_language.md
@ -83,7 +83,7 @@ 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
-    *   {% jdoc core::reporting::ViolationDecorator %}s, to add additional language specific information to the
+    *   {% 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")
--- a/docs/pages/pmd/devdocs/major_contributions/adding_new_cpd_language.md
+++ b/docs/pages/pmd/devdocs/major_contributions/adding_new_cpd_language.md
@ -10,7 +10,7 @@ author: Matías Fraga, Clément Fournier

 ## Adding support for a CPD language

-CPD works generically on the tokens produced by a {% jdoc core::cpd.Tokenizer %}.
+CPD works generically on the tokens produced by a {% jdoc core::cpd.CpdLexer %}.
 To add support for a new language, the crucial piece is writing a CpdLexer that
 splits the source file into the tokens specific to your language. Thankfully you
 can use a stock [Antlr grammar](https://github.com/antlr/grammars-v4) or JavaCC
@ -26,7 +26,7 @@ Use the following guide to set up a new language module that supports CPD.
   - Also add your new module to the dependencies list in "pmd-languages-deps/pom.xml", so that the new language
     is automatically available in the binary distribution (pmd-dist).

-2. Implement a {% jdoc core::cpd.Tokenizer %}.
+2. Implement a {% jdoc core::cpd.CpdLexer %}.
    - For Antlr grammars you can take the grammar from [antlr/grammars-v4](https://github.com/antlr/grammars-v4) and place it in `src/main/antlr4` followed by the package name of the language. You then need to call the appropriate ant wrapper to generate
    the lexer from the grammar. To do so, edit `pom.xml` (eg like [the Golang module](https://github.com/pmd/pmd/tree/master/pmd-go/pom.xml)).
      Once that is done, `mvn generate-sources` should generate the lexer sources for you.
@ -46,7 +46,7 @@ Use the following guide to set up a new language module that supports CPD.
    ```
    
    - For JavaCC grammars, place your grammar in `etc/grammar` and edit the `pom.xml` like the [Python implementation](https://github.com/pmd/pmd/blob/master/pmd-python/pom.xml) does.
-      You can then subclass {% jdoc core::cpd.impl.JavaCCTokenizer %} instead of AntlrTokenizer.
+      You can then subclass {% jdoc core::cpd.impl.JavaccCpdLexer %} instead of AntlrCpdLexer.
    - For any other scenario just implement the interface however you can. Look at the Scala or Apex module for existing implementations.

 3. Create a {% jdoc core::lang.Language %} implementation, and make it implement {% jdoc core::cpd.CpdCapableLanguage %}.
@ -103,9 +103,9 @@ If your language only supports CPD, then you can subclass {% jdoc core::lang.imp
 ### Declaring CpdLexer options

 To make the CpdLexer configurable, first define some property descriptors using
-{% jdoc core::properties.PropertyFactory %}. Look at {% jdoc core::cpd.CpdLexer %}
+{% jdoc core::properties.PropertyFactory %}. Look at {% jdoc core::cpd.CpdLanguageProperties %}
 for some predefined ones which you can reuse (prefer reusing property descriptors if you can).
-You need to override {% jdoc core::Language#newPropertyBundle() %}
+You need to override {% jdoc core::lang.Language#newPropertyBundle() %}
 and call `definePropertyDescriptor` to register the descriptors.
 After that you can access the values of the properties from the parameter
 of {% jdoc core::cpd.CpdCapableLanguage#createCpdTokenizer(core::lang.LanguagePropertyBundle) %}.
@ -120,7 +120,7 @@ Take a look at the [Kotlin token filter implementation](https://github.com/pmd/p
 Add a Maven dependency on `pmd-lang-test` (scope `test`) in your `pom.xml`.
 This contains utilities to test your CpdLexer.

-Create a test class extending from {% jdoc lang-test::cpd.test.CpdTextComparisonTest %}.
+Create a test class extending from {% jdoc lang-test::lang.test.cpd.CpdTextComparisonTest %}.
 To add tests, you need to write regular JUnit `@Test`-annotated methods, and
 call the method `doTest` with the name of the test file.

--- a/docs/pages/pmd/languages/java.md
+++ b/docs/pages/pmd/languages/java.md
@ -138,11 +138,11 @@ A {% jdoc ast::ASTExpression %} might represent a {% jdoc ast::ASTAssignableExpr
 if it e.g. references a variable name. In that case, you can access the referenced variable symbol
 with the method {% jdoc ast::ASTAssignableExpr.ASTNamedReferenceExpr#getReferencedSym() %}.

-Declaration nodes, such as {% jdoc ast::ASTVariableDeclaratorId %} implement the interface
+Declaration nodes, such as {% jdoc ast::ASTVariableId %} implement the interface
 {%jdoc ast::SymbolDeclaratorNode %}. Through the method
 {% jdoc ast::SymbolDeclaratorNode#getSymbol() %} you can also access the symbol.

-To find usages, you can call {% jdoc ast::ASTVariableDeclaratorId#getLocalUsages() %}.
+To find usages, you can call {% jdoc ast::ASTVariableId#getLocalUsages() %}.

 ## Type resolution APIs

--- a/docs/pages/pmd/languages/kotlin.md
+++ b/docs/pages/pmd/languages/kotlin.md
@ -8,6 +8,6 @@ summary: "Kotlin-specific features and guidance"

 [Kotlin](https://kotlinlang.org/) support in PMD is based on the official grammar from <https://github.com/Kotlin/kotlin-spec>.

-{% include language_info.html name='Kotlin' id='kotlin' implementation='kotlin::lang.kotlin.JspLanguageModule' supports_pmd=true supports_cpd=true since=7.0.0 %}
+{% include language_info.html name='Kotlin' id='kotlin' implementation='kotlin::lang.kotlin.KotlinLanguageModule' supports_pmd=true supports_cpd=true since=7.0.0 %}

 Java-based rules and XPath-based rules are supported.
--- a/docs/pages/pmd/languages/language_properties.md
+++ b/docs/pages/pmd/languages/language_properties.md
@ -27,7 +27,7 @@ As a convention, properties whose name start with an *x* are internal and may be
 Properties whose name start with **CPD** are used to configure CPD CpdLexer options.

 Programmatically, the language properties can be set on `PMDConfiguration` (or `CPDConfiguration`) before using the
-{%jdoc core::PmdAnalyzer %} (or {%jdoc core::cpd.CpdAnalyzer %}) instance
+{%jdoc core::PmdAnalysis %} (or {%jdoc core::cpd.CpdAnalysis %}) instance
 to start the analysis:

 ```java
--- a/docs/pages/pmd/languages/velocity.md
+++ b/docs/pages/pmd/languages/velocity.md
@ -9,10 +9,11 @@ summary: "VTL-specific features and guidance"
 > [Velocity](https://velocity.apache.org/engine/devel/vtl-reference.html) is a Java-based template engine.
 > It permits web page designers to reference methods defined in Java code.

-{% include language_info.html name='Velocity Template Language (VTL)' id='velocity' implementation='velocity::lang.velocity.VmLanguageModule' supports_pmd=true supports_cpd=true since='5.1.0' %}
+{% include language_info.html name='Velocity Template Language (VTL)' id='velocity' implementation='velocity::lang.velocity.VtlLanguageModule' supports_pmd=true supports_cpd=true since='5.1.0' %}

 {% capture id_change_note %}
 The language id of the Velocity module was in PMD 6 just "vm". In PMD 7, this has been changed to "velocity". Also the
-package name of the classes has been changed from vm to "velocity".
+package name of the classes has been changed from vm to "velocity". For classes, that used the `Vm` prefix, now `Vtl`
+is used as the prefix, e.g. `VtlLanguageModule`, `VtlNode`.
 {% endcapture %}
 {% include note.html content=id_change_note %}
--- a/docs/pages/pmd/languages/xml.md
+++ b/docs/pages/pmd/languages/xml.md
@ -6,10 +6,10 @@ tags: [languages, PmdCapableLanguage, CpdCapableLanguage]
 summary: "XML-specific features and guidance"
 ---

-{% include language_info.html name='Maven POM' id='pom' implementation='xml::lang.pom.PomLanguageModule' supports_pmd=true supports_cpd=true since='5.4.0' %}
-{% include language_info.html name='WSDL' id='wsdl' implementation='xml::lang.wsdl.WsdlLanguageModule' supports_pmd=true supports_cpd=true since='5.4.0' %}
+{% include language_info.html name='Maven POM' id='pom' implementation='xml::lang.xml.pom.PomLanguageModule' supports_pmd=true supports_cpd=true since='5.4.0' %}
+{% include language_info.html name='WSDL' id='wsdl' implementation='xml::lang.xml.wsdl.WsdlLanguageModule' supports_pmd=true supports_cpd=true since='5.4.0' %}
 {% include language_info.html name='XML' id='xml' implementation='xml::lang.xml.XmlLanguageModule' supports_pmd=true supports_cpd=true since='5.0.0' %}
-{% include language_info.html name='XSL' id='xsl' implementation='xml::lang.xsl.XslLanguageModule' supports_pmd=true supports_cpd=true since='5.0.0' %}
+{% include language_info.html name='XSL' id='xsl' implementation='xml::lang.xml.xsl.XslLanguageModule' supports_pmd=true supports_cpd=true since='5.0.0' %}

 ## The XML language module

@ -46,7 +46,7 @@ for more examples.

 ### XPath rules in XML

-While other languages use {% jdoc core::lang.rule.XPathRule %} to create XPath rules,
+While other languages use {% jdoc core::lang.rule.xpath.XPathRule %} to create XPath rules,
 the use of this class is not recommended for XML languages. Instead, since 6.44.0, you
 are advised to use {% jdoc xml::lang.xml.rule.DomXPathRule %}. This rule class interprets
 XPath queries exactly as regular XPath, while `XPathRule` works on a wrapper for the
--- a/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
+++ b/docs/pages/pmd/userdocs/extending/writing_xpath_rules.md
@ -27,7 +27,7 @@ with opt-in support for XPath 2.0.
 See [the Saxonica documentation](https://www.saxonica.com/html/documentation/expressions/xpath31new.html)
 for an introduction to new features in XPath 3.1.

-The property `version` of {% jdoc core::lang.rule.XPathRule %} is deprecated and
+The property `version` of {% jdoc core::lang.rule.xpath.XPathRule %} is deprecated and
 has been removed with PMD 7.


--- a/docs/pages/pmd/userdocs/incremental_analysis.md
+++ b/docs/pages/pmd/userdocs/incremental_analysis.md
@ -73,7 +73,7 @@ You can think of the cache as a Map where the filepath is used as the key
 and the violations found in previous runs are the value.

 The cache is in the end just a file with serialized data (binary). The implementation is
-{% jdoc core::cache.FileAnalysisCache %}.
+internal: `net.sourceforge.pmd.cache.internal.FileAnalysisCache`.

 #### How does PMD detect whether a file has been changed?

--- a/docs/pages/pmd/userdocs/migrating_to_pmd7.md
+++ b/docs/pages/pmd/userdocs/migrating_to_pmd7.md
@ -564,7 +564,7 @@ See also issue [Deprecate getImage/@Image #4787](https://github.com/pmd/pmd/issu

 #### XML (and POM)

-When using {% jdoc core::lang.rule.XPathRule %}, text of text nodes was exposed as `@Image` of
+When using {% jdoc core::lang.rule.xpath.XPathRule %}, text of text nodes was exposed as `@Image` of
 normal element type nodes. Now the attribute is called `@Text`.

 Note: In general, it is recommended to use {% jdoc xml::lang.xml.rule.DomXPathRule %} instead,
@ -1154,7 +1154,7 @@ List<String> strs;
 ##### Array changes

 * What: Additional nodes {% jdoc jast::ASTArrayType %}, {% jdoc jast::ASTArrayTypeDim %},
-  {% jdoc jast::ASTArrayTypeDims %}, {% jdoc jast::ASTArrayAllocation %}.
+  {% jdoc jast::ASTArrayDimensions %}, {% jdoc jast::ASTArrayAllocation %}.
 * Why: Support annotated array types ([[java] Java8 parsing corner case with annotated array types (#997)](https://github.com/pmd/pmd/issues/997))
 * Related issue: [[java] Simplify array allocation expressions (#1981)](https://github.com/pmd/pmd/pull/1981)

@ -2790,23 +2790,23 @@ The amount of changes in the grammar that this change entails is enormous,
 but hopefully firing up the designer to inspect the new structure should
 give you the information you need quickly.

-Note: this doesn't affect binary expressions like {% jdoc jast::ASTAdditiveExpression %}.
+Note: this also affect binary expressions like {% jdoc jast::ASTInfixExpression %}.
 E.g. `a+b+c` is not parsed as
 ```
 AdditiveExpression
-+ AdditiveExpression
-  + (a)
-  + (b)
-+ (c)  
-``` 
-It's still
-```
-AdditiveExpression
 + (a)
 + (b)
-+ (c)  
-``` 
-which is easier to navigate, especially from XPath.
+ (c)
+```
+
+But it is now (note: AdditiveExpression is now InfixExpression)
+```
+InfixExpression
+ InfixExpression
+  + (a)
+  + (b)
+ (c)
+```

 ##### Field access, array access, variable access

--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@ -701,7 +701,7 @@ If you import rules, you also need to adjust the paths, e.g.
 #### Other changes

 The information about changed rules, removed rules and rulesets
-can be found in the [Detailed Release Notes for PMD 7]({{ baseurl }}pmd_release_notes_pmd7.html#-new-and-changed-rules)
+can be found in the [Detailed Release Notes for PMD 7]({{ baseurl }}pmd_release_notes_pmd7.html#-new-and-changed-rules).

 ### 🚨 API

@ -741,7 +741,7 @@ Many thanks to the following contributors:
@Debamoy, @eklimo, @ethauvin, @JerritEic, @joaodinissf, @kenji21, @krdabrowski, @lbovet, @lsoncini,
@LynnBroe, @marcindabrowski, @matifraga, @mohan-chinnappan-n, @mohui1999, @nawforce, @nirvikpatel,
@nwcm, @pguyot, @PimvanderLoos, @rcorfieldffdc, @sfdcsteve, @shai-bennathan, @tomidelucca,
-@tprouvot, @wener-tiobe
+@tprouvot, @wener-tiobe.

 See [Detailed Release Notes for PMD 7]({{ baseurl }}pmd_release_notes_pmd7.html#-external-contributions) for the
 full list of PRs.
--- a/docs/pages/release_notes_pmd7.md
+++ b/docs/pages/release_notes_pmd7.md
--- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/MetricsUtil.java
+++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/MetricsUtil.java
@ -76,6 +76,8 @@ public final class MetricsUtil {
     * @param node The node on which to compute the metric
     *
     * @return The value of the metric, or {@code Double.NaN} if the value couldn't be computed
+     *
+     * @throws IllegalArgumentException If the metric does not support the given node
     */
    public static <N extends Node, R extends Number> R computeMetric(Metric<? super N, R> key, N node) {
        return computeMetric(key, node, MetricOptions.emptyOptions());