From e270d57d431229d2146e46f95aa77704d8170f54 Mon Sep 17 00:00:00 2001 From: "PMD CI (pmd-bot)" Date: Fri, 15 Mar 2024 17:11:36 +0000 Subject: [PATCH] Update documentation https://github.com/pmd/pmd/actions/runs/8299575336 https://github.com/pmd/pmd/compare/b79518191d2e...7d9dc2fcb65b --- css/customstyles.css | 4 - feed.xml | 4 +- pmd_about_help.html | 2 +- pmd_devdocs_development.html | 16 +- ...devdocs_major_adding_new_cpd_language.html | 12 +- ...vdocs_major_adding_new_language_antlr.html | 2 +- ...docs_major_adding_new_language_javacc.html | 2 +- pmd_languages_apex.html | 23 +- pmd_languages_coco.html | 23 +- pmd_languages_configuration.html | 2 +- pmd_languages_cpp.html | 23 +- pmd_languages_cs.html | 23 +- pmd_languages_dart.html | 23 +- pmd_languages_fortran.html | 23 +- pmd_languages_gherkin.html | 23 +- pmd_languages_go.html | 23 +- pmd_languages_groovy.html | 23 +- pmd_languages_html.html | 23 +- pmd_languages_java.html | 27 +- pmd_languages_js_ts.html | 46 +- pmd_languages_jsp.html | 23 +- pmd_languages_julia.html | 23 +- pmd_languages_kotlin.html | 23 +- pmd_languages_lua.html | 23 +- pmd_languages_matlab.html | 23 +- pmd_languages_modelica.html | 25 +- pmd_languages_objectivec.html | 23 +- pmd_languages_perl.html | 23 +- pmd_languages_php.html | 23 +- pmd_languages_plsql.html | 23 +- pmd_languages_python.html | 23 +- pmd_languages_ruby.html | 23 +- pmd_languages_scala.html | 23 +- pmd_languages_swift.html | 23 +- pmd_languages_tsql.html | 23 +- pmd_languages_velocity.html | 26 +- pmd_languages_visualforce.html | 23 +- pmd_languages_xml.html | 94 +- pmd_projectdocs_trivia_news.html | 4 +- pmd_release_notes.html | 1059 ++------ pmd_release_notes_pmd7.html | 2341 +++++++++++------ pmd_rules_java.html | 2 +- pmd_rules_java_errorprone.html | 2 +- pmd_rules_java_performance.html | 8 +- pmd_userdocs_cli_reference.html | 2 +- pmd_userdocs_cpd.html | 2 +- ...serdocs_extending_writing_xpath_rules.html | 2 +- pmd_userdocs_incremental_analysis.html | 2 +- pmd_userdocs_installation.html | 2 +- pmd_userdocs_migrating_to_pmd7.html | 1010 ++++--- pmd_userdocs_tools_gradle.html | 10 +- tag_devdocs.html | 2 +- 52 files changed, 2605 insertions(+), 2680 deletions(-) diff --git a/css/customstyles.css b/css/customstyles.css index 98b6bee046..ba7a6b256d 100644 --- a/css/customstyles.css +++ b/css/customstyles.css @@ -1175,10 +1175,6 @@ a code { color: #248ec2; } -code + a > code { - margin-left: -7px; -} - table th code { color: white; } diff --git a/feed.xml b/feed.xml index 61bb6e019c..fc0189d484 100644 --- a/feed.xml +++ b/feed.xml @@ -5,8 +5,8 @@ Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features. https://docs.pmd-code.org/latest/ - Fri, 15 Mar 2024 13:39:10 +0000 - Fri, 15 Mar 2024 13:39:10 +0000 + Fri, 15 Mar 2024 17:08:26 +0000 + Fri, 15 Mar 2024 17:08:26 +0000 Jekyll v3.9.5 diff --git a/pmd_about_help.html b/pmd_about_help.html index b4c3f17429..d00105253b 100644 --- a/pmd_about_help.html +++ b/pmd_about_help.html @@ -1888,7 +1888,7 @@

  • Or you can join the Mailing List or browse -through the archives (archive1, archive2).

    +through the mailing list archive.

  • Of course, you can also directly jump to our source code on github.

    diff --git a/pmd_devdocs_development.html b/pmd_devdocs_development.html index d3964a8e78..c72d2f14d5 100644 --- a/pmd_devdocs_development.html +++ b/pmd_devdocs_development.html @@ -1871,11 +1871,9 @@
    -

    The next version of PMD will be developed in parallel with this release. We will release additional bugfix versions as needed.

    +

    Source Code

    -

    Source Code

    - -

    The complete source code can be found on github:

    +

    The complete source code can be found on Github:

    • github.com/pmd/pmd - main PMD repository. Includes all the code to support all languages, including this documentation.
      • @@ -1887,7 +1885,7 @@

      Continuous Integration

      -

      We use Travis CI as our ci service. The main repo and the eclipse plugin are built for +

      We use GitHub Actions as our ci service. The main repo and the eclipse plugin are built for every push. Each pull request is built as well.

      The maven snapshot artifacts are deployed at Sonatypes OSS snapshot repository.

      @@ -1896,7 +1894,11 @@ every push. Each pull request is built as well.

      Documentation and Webpages

      -

      A snapshot of the web site for the new version is generated travis-ci as well.

      +

      Main documentation server is docs.pmd-code.org.

      + +

      A snapshot of the web site for the new version is generated by the ci job as well.

      + +

      The latest release documentation is always available under docs.pmd-code.org/latest

      Contributing

      @@ -1942,7 +1944,7 @@ every push. Each pull request is built as well.

      ©2024 PMD Open Source Project. All rights reserved.
      Page last updated: - August 2017
      Site last generated: Mar 15, 2024
      + March 2024
      Site last generated: Mar 15, 2024

      PMD logo diff --git a/pmd_devdocs_major_adding_new_cpd_language.html b/pmd_devdocs_major_adding_new_cpd_language.html index ce4370b4b8..6aff4061f1 100644 --- a/pmd_devdocs_major_adding_new_cpd_language.html +++ b/pmd_devdocs_major_adding_new_cpd_language.html @@ -1875,7 +1875,7 @@

      Adding support for a CPD language

      -

      CPD works generically on the tokens produced by a Tokenizer. +

      CPD works generically on the tokens produced by a 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 or JavaCC @@ -1894,7 +1894,7 @@ other languages. is automatically available in the binary distribution (pmd-dist).

    • -
  • Implement a Tokenizer. +
  • Implement a CpdLexer.

    • For Antlr grammars you can take the grammar from 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 @@ -1918,7 +1918,7 @@ Once that is done, mvn genera

      • For JavaCC grammars, place your grammar in etc/grammar and edit the pom.xml like the Python implementation does. -You can then subclass JavaCCTokenizer instead of AntlrTokenizer.
        • +You can then subclass 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.
      • @@ -1979,9 +1979,9 @@ There is also the following Jekyll Include, that creates summary box for the lan

      Declaring CpdLexer options

      To make the CpdLexer configurable, first define some property descriptors using -PropertyFactory. Look at CpdLexer +PropertyFactory. Look at CpdLanguageProperties for some predefined ones which you can reuse (prefer reusing property descriptors if you can). -You need to override newPropertyBundle +You need to override newPropertyBundle and call definePropertyDescriptor to register the descriptors. After that you can access the values of the properties from the parameter of createCpdTokenizer.

      @@ -1995,7 +1995,7 @@ Take a look at the pmd-lang-test       (scope test) in your pom.xml. This contains utilities to test your CpdLexer.

      -

      Create a test class extending from CpdTextComparisonTest. +

      Create a test class extending from 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.

      diff --git a/pmd_devdocs_major_adding_new_language_antlr.html b/pmd_devdocs_major_adding_new_language_antlr.html index cc67d71289..2b90e73e83 100644 --- a/pmd_devdocs_major_adding_new_language_antlr.html +++ b/pmd_devdocs_major_adding_new_language_antlr.html @@ -2029,7 +2029,7 @@ implementation that you need to extend to create your own adapter as we do with
    • It can be used to provide other features for your language like
      • violation suppression logic
        • -
      • reportings, to add additional language specific information to the +
      • ViolationDecorators, to add additional language specific information to the created violations. The Java language module uses this to provide the method name or class name, where the violation occurred.
      • metrics
        • diff --git a/pmd_devdocs_major_adding_new_language_javacc.html b/pmd_devdocs_major_adding_new_language_javacc.html index e7d2ab4c3d..b03e7840cf 100644 --- a/pmd_devdocs_major_adding_new_language_javacc.html +++ b/pmd_devdocs_major_adding_new_language_javacc.html @@ -1965,7 +1965,7 @@ all the available tokens in the field
  • pmd-java
  • pmd-apex
    • @@ -5096,11 +5201,11 @@ to refer to nodes generically.
  • Concrete node classes will be made final with 7.0.0.
  • Setters found in any node class or interface. Rules should consider the AST immutable. We will make those setters package private with 7.0.0.
    • -
  • The class JspParser is deprecated and should not be used directly. -Use LanguageVersionHandler#getParser instead.
    • +
  • The class JspParser is deprecated and should not be used directly. +Use LanguageVersionHandler#getParser instead.
    • -

    Please look at net.sourceforge.pmd.lang.jsp.ast to find out the full list of deprecations.

    +

    Please look at net.sourceforge.pmd.lang.jsp.ast to find out the full list of deprecations.

    In ASTs (Velocity)

    @@ -5115,25 +5220,25 @@ which for rules, means that they never need to instantiate node themselves. Those constructors will be made package private with 7.0.0.
  • Subclassing of abstract node classes, or usage of their type. The base classes are internal API and will be hidden in version 7.0.0. You should not couple your code to them.
    • -
  • In the meantime you should use interfaces like VmNode or +
  • In the meantime you should use interfaces like VtlNode or Node, or the other published interfaces in this package, to refer to nodes generically.
  • Concrete node classes will be made final with 7.0.0.
  • Setters found in any node class or interface. Rules should consider the AST immutable. We will make those setters package private with 7.0.0.
    • -
  • The package net.sourceforge.pmd.lang.vm.directive as well as the classes -DirectiveMapper and LogUtil are deprecated +
  • The package net.sourceforge.pmd.lang.vm.directive as well as the classes +DirectiveMapper and LogUtil are deprecated for removal. They were only used internally during parsing.
    • -
  • The class VmParser is deprecated and should not be used directly. -Use LanguageVersionHandler#getParser instead.
    • +
  • The class VmParser is deprecated and should not be used directly. +Use LanguageVersionHandler#getParser instead.
    • -

    Please look at net.sourceforge.pmd.lang.vm.ast to find out the full list of deprecations.

    +

    Please look at net.sourceforge.pmd.lang.vm.ast to find out the full list of deprecations.

    PLSQL AST

    -

    The production and node ASTCursorBody was unnecessary, not used and has been removed. Cursors have been already -parsed as ASTCursorSpecification.

    +

    The production and node ASTCursorBody was unnecessary, not used and has been removed. Cursors have been already +parsed as ASTCursorSpecification.

    6.21.0

    @@ -5145,34 +5250,34 @@ parsed as ASTCursorSpecificat You can identify them with the @InternalApi annotation. You’ll also get a deprecation warning.

    - +

    Installation

    diff --git a/pmd_userdocs_migrating_to_pmd7.html b/pmd_userdocs_migrating_to_pmd7.html index 9f57440fcf..0f2405c12a 100644 --- a/pmd_userdocs_migrating_to_pmd7.html +++ b/pmd_userdocs_migrating_to_pmd7.html @@ -2493,7 +2493,7 @@ by deprecating the attribute and providing alternatives.

    XML (and POM)

    -

    When using XPathRule, text of text nodes was exposed as @Image of +

    When using 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 DomXPathRule instead, @@ -2538,10 +2538,9 @@ type is used to share the disambiguation logic.

    - -

    Annotation AST Examples</summary>

    + Annotation AST Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -2675,24 +2674,23 @@ type is used to share the disambiguation logic.
    -

    </details>

    +
    -
    Annotation nesting
    +
    Annotation nesting
    - -
    - -

    Annotation nesting Examples</summary>

    +
    + Annotation nesting Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    Method @@ -3011,52 +3009,51 @@ Enum constants
    -

    </details>

    +
    -

    Types

    +

    Types

    -
    Type and ReferenceType
    +
    Type and ReferenceType
    -
      -
    • What: -
        -
      • ASTType and ASTReferenceType have been turned into +
          +
        • What: + -
          • -
        • Why: -
            -
          • some syntactic contexts only allow reference types, other allow any kind of type. If you want to match all types +
          +
          • +
        • Why: +
            +
          • some syntactic contexts only allow reference types, other allow any kind of type. If you want to match all types of a program, then matching Type would be the intuitive solution. But in 6.0.x, it wouldn’t have sufficed, since in some contexts, no Type node was pushed, only a ReferenceType
            • -
          • Regardless of the original syntactic context, any reference type is a type, and searching for ASTType should +
          • Regardless of the original syntactic context, any reference type is a type, and searching for ASTType should yield all the types in the tree.
            • -
          • Using interfaces allows to abstract behaviour and make a nicer and safer API.
            • -
          -
          • -
        • Migrating -
            -
          • There is currently no way to match abstract types (or interfaces) with XPath, so Type +
          • Using interfaces allows to abstract behaviour and make a nicer and safer API.
            • +
          +
          • +
        • Migrating +
            +
          • There is currently no way to match abstract types (or interfaces) with XPath, so Type and ReferenceType name tests won’t match anything anymore.
            • -
          • Type/ReferenceType/ClassOrInterfaceType ➡️ ClassType
            • -
          • Type/PrimitiveType ➡️ PrimitiveType.
            • -
          • Type/ReferenceType[@ArrayDepth > 1]/ClassOrInterfaceType ➡️ ArrayType/ClassType.
            • -
          • Type/ReferenceType/PrimitiveType ➡️ ArrayType/PrimitiveType.
            • -
          • Note that in most cases you should check the type of a variable with e.g. +
          • Type/ReferenceType/ClassOrInterfaceType ➡️ ClassType
            • +
          • Type/PrimitiveType ➡️ PrimitiveType.
            • +
          • Type/ReferenceType[@ArrayDepth > 1]/ClassOrInterfaceType ➡️ ArrayType/ClassType.
            • +
          • Type/ReferenceType/PrimitiveType ➡️ ArrayType/PrimitiveType.
            • +
          • Note that in most cases you should check the type of a variable with e.g. VariableId[pmd-java:typeIs("java.lang.String[]")] because it considers the additional dimensions on declarations like String foo[];. The Java equivalent is TypeHelper.isA(id, String[].class);
            • -
          -
          • -
        +
      +
      • +
    -
    - -

    Type and ReferenceType Examples</summary>

    +
    + Type and ReferenceType Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3096,22 +3093,21 @@ The Java equivalent is TypeHe
    -

    </details>

    +
    -
    Array changes
    +
    Array changes
    - + -
    - -

    Array Examples</summary>

    +
    + Array Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3245,22 +3241,21 @@ The Java equivalent is TypeHe
    -

    </details>

    +
    -
    ClassType nesting
    +
    ClassType nesting
    - -
    - -

    ClassType Examples</summary>

    +
    + ClassType Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3319,28 +3314,27 @@ and encloses its qualifying type.
    -

    </details>

    +
    -
    TypeArgument and WildcardType
    +
    TypeArgument and WildcardType
    -
      -
    • What: -
        -
      • ASTTypeArgument is removed. Instead, the ASTTypeArguments node contains directly +
          +
        • What: + -
          • -
        • Why: Because wildcard types are types in their own right, and having a node to represent them skims several levels +
        • The ASTWildcardBounds node is removed. Instead, the bound is a direct child of the WildcardType.
          • +
        +
        • +
      • Why: Because wildcard types are types in their own right, and having a node to represent them skims several levels of nesting off.
        • -
      +
    -
    - -

    TypeArgument and WildcardType Examples</summary>

    +
    + TypeArgument and WildcardType Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3393,25 +3387,24 @@ of nesting off.
    -

    </details>

    +
    -

    Declarations

    +

    Declarations

    -
    Import and Package declarations
    +
    Import and Package declarations
    - -
    - -

    Import and Package declarations Examples</summary>

    +
    + Import and Package declarations Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3455,27 +3448,26 @@ It’s too ambiguous to treat in the parser and could just be the image of the i
    -

    </details>

    +
    -
    Modifier lists
    +
    Modifier lists
    -
      -
    • What: ModifierOwner (formerly AccessNode) is now based on a node: ASTModifierList. +
        +
      • What: ModifierOwner (formerly AccessNode) is now based on a node: ASTModifierList. That node represents modifiers occurring before a declaration. It provides a flexible API to query modifiers, both explicit and implicit. All declaration nodes now have such a modifier list, even if it’s implicit (no explicit modifiers).
        • -
      • Why: ModifierOwner (formerly AccessNode) gave a lot of irrelevant methods to its subtypes. +
      • Why: ModifierOwner (formerly AccessNode) gave a lot of irrelevant methods to its subtypes. E.g. ASTFieldDeclaration::isSynchronized makes no sense. Now, these irrelevant methods don’t clutter the API. The API of ModifierList is both more general and flexible.
        • -
      • Related issue: [java] Rework AccessNode (#2259)
        • -
      +
    • Related issue: [java] Rework AccessNode (#2259)
      • +
    -
    - -

    Modifier lists Examples</summary>

    +
    + Modifier lists Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    Method @@ -3549,23 +3541,22 @@ Top-level type declaration
    -

    </details>

    +
    -
    Flattened body declarations
    +
    Flattened body declarations
    - -
    - -

    Flattened body declarations Examples</summary>

    +
    + Flattened body declarations Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3639,22 +3630,21 @@ These were unnecessary since annotations are nested (see above Module declarations +
    Module declarations
    -     -
    - -

    Module declarations Examples</summary>

    +
    + Module declarations Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3716,27 +3706,26 @@ uses specific node types for different directives (requires, exports, uses, prov
    -

    </details>

    +
    -
    Anonymous class declarations
    +
    Anonymous class declarations
    - -
    - -

    Anonymous class declarations Examples</summary>

    +
    + Anonymous class declarations Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3778,26 +3767,25 @@ and enums.
    -

    </details>

    +
    -

    Method and Constructor declarations

    +

    Method and Constructor declarations

    -
    Method grammar simplification
    +
    Method grammar simplification
    -
      -
    • What: Simplify and align the grammar used for method and constructor declarations. The methods in an annotation +
        +
      • What: Simplify and align the grammar used for method and constructor declarations. The methods in an annotation type are now also method declarations.
        • -
      • Why: The method declaration had a nested node “MethodDeclarator”, which was not available for constructor +
      • Why: The method declaration had a nested node “MethodDeclarator”, which was not available for constructor declarations. This made it difficult to write rules, that concern both methods and constructors without explicitly differentiate between these two.
        • -
      • Related issue: [java] Align method and constructor declaration grammar (#2034)
        • -
      +
    • Related issue: [java] Align method and constructor declaration grammar (#2034)
      • +
    -
    - -

    Method grammar Examples</summary>

    +
    + Method grammar Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -3899,28 +3887,27 @@ explicitly differentiate between these two.
    -

    </details>

    +
    -
    Formal parameters
    +
    Formal parameters
    -
      -
    • What: Use ASTFormalParameter only for method and constructor declaration. Lambdas use +
        +
      • What: Use ASTFormalParameter only for method and constructor declaration. Lambdas use ASTLambdaParameter, catch clauses use ASTCatchParameter.
        • -
      • Why: FormalParameter’s API is different from the other ones. -
          -
        • FormalParameter must mention a type node.
          • -
        • LambdaParameter can be inferred
          • -
        • CatchParameter cannot be varargs
          • -
        • CatchParameter can have multiple exception types (a ASTUnionType now)
          • -
        -
        • -
      +
    • Why: FormalParameter’s API is different from the other ones. +
        +
      • FormalParameter must mention a type node.
        • +
      • LambdaParameter can be inferred
        • +
      • CatchParameter cannot be varargs
        • +
      • CatchParameter can have multiple exception types (a ASTUnionType now)
        • +
      +
      • +
    -
    - -

    Formal parameters Examples</summary>

    +
    + Formal parameters Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4061,24 +4048,23 @@ explicitly differentiate between these two.
    -

    </details>

    +
    -
    New node for explicit receiver parameter
    +
    New node for explicit receiver parameter
    - -
    - -

    explicit receiver parameter Examples</summary>

    +
    + explicit receiver parameter Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4116,20 +4102,19 @@ and Varargs +
    Varargs
    -     +
      +
    • What: parse the varargs ellipsis as an ASTArrayType.
      • +
    • Why: this improves regularity of the grammar, and allows type annotations to be added to the ellipsis
      • +
    -
    - -

    Varargs Examples</summary>

    +
    + Varargs Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4211,21 +4196,20 @@ and Add void type node to replace ResultType +
    Add void type node to replace ResultType
    -     + -
    - -

    Void Type Examples</summary>

    +
    + Void Type Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4270,28 +4254,27 @@ and Statements +

    Statements

    -
    Statements are flattened
    +
    Statements are flattened
    -     -
    - -

    Statements Examples</summary>

    +
    + Statements Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4335,23 +4318,22 @@ This is a parser-only distinction that’s not that useful for analysis later on
    -

    </details>

    +
    -
    New node for For-each statements
    +
    New node for For-each statements
    -
      -
    • What: New node for For-each statements: ASTForeachStatement instead of ForStatement.
      • -
    • Why: This makes it a lot easier to distinguish in the AST between For-loops and For-Each-loops. E.g. some +
        +
      • What: New node for For-each statements: ASTForeachStatement instead of ForStatement.
        • +
      • Why: This makes it a lot easier to distinguish in the AST between For-loops and For-Each-loops. E.g. some rules only apply to one or the other, and it was complicated to write a rule that works with both different subtrees (for loops have additional children ForInit and ForUpdate)
        • -
      • Related issue: [java] Improve statement grammar (#2164)
        • -
      +
    • Related issue: [java] Improve statement grammar (#2164)
      • +
    -
    - -

    For-each statement Examples</summary>

    +
    + For-each statement Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4406,27 +4388,26 @@ subtrees (for loops have additional children ForInit and ForUpdate)
    -

    </details>

    +
    -
    New nodes for ExpressionStatement, LocalClassStatement
    +
    New nodes for ExpressionStatement, LocalClassStatement
    - -
    - -

    ExpressionStatement, LocalClassStatement Examples</summary>

    +
    + ExpressionStatement, LocalClassStatement Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4461,22 +4442,21 @@ This allows us to have two distinct hierarchies for expressions and statements.<
    -

    </details>

    +
    -
    Improve try-with-resources grammar
    +
    Improve try-with-resources grammar
    - -
    - -

    Try-With-Resources Examples</summary>

    +
    + Try-With-Resources Examples - +
    - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4550,56 +4530,55 @@ It uses now Expressions +

    Expressions

    -
      -
    • -

      ASTExpression and ASTPrimaryExpression have +

        +
      • +

        ASTExpression and ASTPrimaryExpression have been turned into interfaces. These added no information to the AST and increased its depth unnecessarily. All expressions implement the first interface. Both of those nodes can no more be found in ASTs.

        -
        • -
      • -

        Migrating:

        -
          -
        • Basically, Expression/X or Expression/PrimaryExpression/X, just becomes X
          • -
        • There is currently no way to match abstract or interface types with XPath, so Expression or PrimaryExpression +
          • +
        • +

          Migrating:

          +
            +
          • Basically, Expression/X or Expression/PrimaryExpression/X, just becomes X
            • +
          • There is currently no way to match abstract or interface types with XPath, so Expression or PrimaryExpression name tests won’t match anything anymore. However, the axis step *[@Expression=true()] matches any expression.
            • -
          -
          • -
        +
      +
      • +
    -
    New nodes for different literals types
    +
    New nodes for different literals types
    - -
    - -

    Literals Examples</summary>

    +
    + Literals Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4631,28 +4610,27 @@ by it was inconsistent, and ultimately that level of nesting was unnecessary.
    -

    </details>

    +
    -
    Method calls, constructor calls, array allocations
    +
    Method calls, constructor calls, array allocations
    - -
    - -

    Method calls, constructor calls, array allocations Examples</summary>

    +
    + Method calls, constructor calls, array allocations Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4747,22 +4725,21 @@ primary prefix, suffix and expressions. This was too low level to be easy to be
    -

    </details>

    +
    -
    Method call chains are left-recursive
    +
    Method call chains are left-recursive
    - -
    - -

    Method call chain Examples</summary>

    +
    + Method call chain Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4799,63 +4776,62 @@ grammar. Subtrees for primary expressions appear to be left-recursive now.
    -

    </details>

    +
    -

    Instead of being flat, the subexpressions are now nested within one another. +

    Instead of being flat, the subexpressions are now nested within one another. The nesting follows the naturally recursive structure of expressions:

    - 
    new Foo().bar.foo(1)
+
    new Foo().bar.foo(1)
 └───────┘   │      │ ConstructorCall
 └───────────┘      │ FieldAccess
 └──────────────────┘ MethodCall
-
                                                                                                
    
+
    -

    This makes the AST more regular and easier to navigate. Each node contains +

    This makes the AST more regular and easier to navigate. Each node contains the other nodes that are relevant to it (e.g. arguments) instead of them being spread out over several siblings. The API of all nodes has been enriched with high-level accessors to query the AST in a semantic way, without bothering with the placement details.

    -

    The amount of changes in the grammar that this change entails is enormous, +

    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 ASTAdditiveExpression. +

    Note: this also affect binary expressions like ASTInfixExpression. E.g. a+b+c is not parsed as

    - 
    AdditiveExpression
-+ AdditiveExpression
-  + (a)
-  + (b)
-+ (c)  
-
    -

    It’s still

    - 
    AdditiveExpression
+
    AdditiveExpression
 + (a)
 + (b)
-+ (c)  
-
                                                                                                
    
-                                                                                            
    which is easier to navigate, especially from XPath.
    
++ (c)
+
    -
    Field access, array access, variable access
    +

    But it is now (note: AdditiveExpression is now InfixExpression)

    +
    InfixExpression
++ InfixExpression
+  + (a)
+  + (b)
++ (c)
+
    - -
    - -

    Field access, array access, variable access Examples</summary>

    +
    + Field access, array access, variable access Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -4953,26 +4929,25 @@ Also provide info about the access type, like whether a variable is read or writ
    -

    </details>

    +
    -
    Explicit nodes for this/super expressions
    +
    Explicit nodes for this/super expressions
    - + -
    - -

    this/super expressions Examples</summary>

    +
    + this/super expressions Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -5052,22 +5027,21 @@ Also provide info about the access type, like whether a variable is read or writ
    -

    </details>

    +
    -
    Type expressions
    +
    Type expressions
    - -
    - -

    Type expressions Examples</summary>

    +
    + Type expressions Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -5138,35 +5112,34 @@ Also provide info about the access type, like whether a variable is read or writ
    -

    </details>

    +
    -
    Merge unary expressions
    +
    Merge unary expressions
    - -
    - -

    Unary Expressions Examples</summary>

    +
    + Unary Expressions Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -5249,28 +5222,27 @@ so that using a single node is appropriate.
    -

    </details>

    +
    -
    Binary operators are left-recursive
    +
    Binary operators are left-recursive
    -
      -
    • What: For each operator, there were separate AST nodes (like AdditiveExpression, AndExpression, …). +
        +
      • What: For each operator, there were separate AST nodes (like AdditiveExpression, AndExpression, …). These are now unified into a InfixExpression, which gives access to the operator via getOperator() and to the operands (getLhs(), getRhs()). Additionally, the resulting AST is not flat anymore, but a more structured tree.
        • -
      • Why: Having different AST node types doesn’t add information, that the operator doesn’t already provide. +
      • Why: Having different AST node types doesn’t add information, that the operator doesn’t already provide. The new structure as a result, that the expressions are now parsed left recursive, makes the AST more JLS-like. This makes it easier for the type mapping algorithms. It also provides the information, which operands are used with which operator. This information was lost if more than 2 operands where used and the tree was flattened with PMD 6.
        • -
      • Related issue: [java] Make binary operators left-recursive (#1979)
        • -
      +
    • Related issue: [java] Make binary operators left-recursive (#1979)
      • +
    -
    - -

    Binary operators Examples</summary>

    +
    + Binary operators Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -5306,23 +5278,22 @@ flattened with PMD 6.
    -

    </details>

    +
    -
    Parenthesized expressions
    +
    Parenthesized expressions
    -
      -
    • What: Parentheses are not modelled in the AST anymore, but can be checked with the attributes @Parenthesized +
        +
      • What: Parentheses are not modelled in the AST anymore, but can be checked with the attributes @Parenthesized and @ParenthesisDepth
        • -
      • Why: This keeps the tree flat while still preserving the information. The tree is the same in case of unnecessary +
      • Why: This keeps the tree flat while still preserving the information. The tree is the same in case of unnecessary parenthesis, which makes it harder to fool rules that look at the structure of the tree.
        • -
      • Related issue: [java] Remove ParenthesizedExpr (#1872)
        • -
      +
    • Related issue: [java] Remove ParenthesizedExpr (#1872)
      • +
    -
    - -

    Parenthesized expressions Examples</summary>

    +
    + Parenthesized expressions Examples - +
    CodeOld AST (PMD 6)New AST (PMD 7)
    @@ -5358,171 +5329,114 @@ parenthesis, which makes it harder to fool rules that look at the structure of t
    -

    </details>

    +
    -

    Apex AST

    +

    Apex AST

    -

    PMD 7.0.0 switched the underlying parser for Apex code from Jorje to Summit AST, +

    PMD 7.0.0 switched the underlying parser for Apex code from Jorje to Summit AST, which is based on an open source grammar for Apex: apex-parser.

    -

    The produced AST is mostly compatible, there are some unavoidable changes however:

    +

    The produced AST is mostly compatible, there are some unavoidable changes however:

    -
      -
    • Node Method (ASTMethod) -
        -
      • No attribute @Synthetic anymore. Unlike Jorje, Summit AST doesn’t generate synthetic methods anymore, so +
          +
        • Node Method (ASTMethod) +
            +
          • No attribute @Synthetic anymore. Unlike Jorje, Summit AST doesn’t generate synthetic methods anymore, so this attribute would have been always false and is of no use. Therefore it has been removed completely.
            • -
          • There will be no methods anymore with the name <clinit>, <init>.
            • -
          -
          • -
        • There is no node BridgeMethodCreator anymore. This was an artificially generated node by Jorje. Since the +
        • There will be no methods anymore with the name <clinit>, <init>.
          • +
        +
        • +
      • There is no node BridgeMethodCreator anymore. This was an artificially generated node by Jorje. Since the new parser doesn’t generate synthetic methods anymore, this node is not needed anymore.
        • -
      • There is in general no attribute @Namespace anymore. The attribute has been removed, as it was never fully +
      • There is in general no attribute @Namespace anymore. The attribute has been removed, as it was never fully implemented. It always returned an empty string.
        • -
      • Node ReferenceExpression (ASTReferenceExpression) -
          -
        • No attribute @Context anymore. It was not used and always returned null.
          • -
        -
        • -
      +
    • Node ReferenceExpression (ASTReferenceExpression) +
        +
      • No attribute @Context anymore. It was not used and always returned null.
        • +
      +
      • +
    -

    Language versions

    +

    Language versions

    -
      -
    • Since all languages now have defined language versions, you could now write rules that apply only for specific +
        +
      • Since all languages now have defined language versions, you could now write rules that apply only for specific versions (using minimumLanguageVersion and maximumLanguageVersion).
        • -
      • All languages have a default version. If no specific version on the CLI is given using --use-version, then +
      • All languages have a default version. If no specific version on the CLI is given using --use-version, then this default version will be used. Usually the latest version is the default version.
        • -
      • The available versions for each language can be seen in the help message of the CLI pmd check --help.
        • -
      • See also Changed: Language versions
        • -
      +
    • The available versions for each language can be seen in the help message of the CLI pmd check --help.
      • +
    • See also Changed: Language versions
      • +
    -

    Migrating custom CPD language modules

    +

    Migrating custom CPD language modules

    -

    This is only relevant, if you are maintaining a CPD language module for a custom language.

    +

    This is only relevant, if you are maintaining a CPD language module for a custom language.

    -
      -
    • Instead of AbstractLanguage extend now CpdOnlyLanguageModuleBase.
      • -
    • Instead of AntlrTokenManager use now TokenManager
      • -
    • Instead of AntlrTokenFilter also use now TokenManager
      • -
    • Instead of AntlrTokenFilter extend now BaseTokenFilter
      • -
    • CPD Module discovery change. The service loader won’t load anymore src/main/resources/META-INF/services/net.sourceforge.pmd.cpd.Language + +
    -

    Build Tools

    +

    Build Tools

    - + +
  • See Support for PMD 7.0
    • + -

    XML Report Format

    +

    XML Report Format

    -

    The XML Report format supports rendering suppressed violations.

    +

    The XML Report format supports rendering suppressed violations.

    -

    The content of the attribute suppressiontype is changed in PMD 7.0.0:

    -
      -
    • nopmd ➡️ //nopmd
      • -
    • annotation ➡️ @suppresswarnings
      • -
    • xpath - new value. Suppressed via property “violationSuppressXPath”.
      • -
    • regex - new value. Suppressed via property “violationSuppressRegex”.
      • -
    -     -
    -     -
    -     -
    -     -
    -     -
    -     -
    -     -
    -     -
    -     -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

    The content of the attribute suppressiontype is changed in PMD 7.0.0:

    +
      +
    • nopmd ➡️ //nopmd
      • +
    • annotation ➡️ @suppresswarnings
      • +
    • xpath - new value. Suppressed via property “violationSuppressXPath”.
      • +
    • regex - new value. Suppressed via property “violationSuppressRegex”.
      • +
    diff --git a/pmd_userdocs_tools_gradle.html b/pmd_userdocs_tools_gradle.html index 6d31afadb7..4167cf9db8 100644 --- a/pmd_userdocs_tools_gradle.html +++ b/pmd_userdocs_tools_gradle.html @@ -1921,14 +1921,14 @@ with the property toolVersion

    Source code for Gradles PMD Plugin is available here:

    diff --git a/tag_devdocs.html b/tag_devdocs.html index 57a0a31a10..58c5034926 100644 --- a/tag_devdocs.html +++ b/tag_devdocs.html @@ -2089,7 +2089,7 @@
    Developer Resources Page The next version of PMD will be developed in parallel with this release. We will release additional bugfix versions as needed. Source Code The complete source code can be found on github: github.com/pmd/pmd - main PMD repository. Includes all the code to support all languages, including this... Source Code The complete source code can be found on Github: github.com/pmd/pmd - main PMD repository. Includes all the code to support all languages, including this documentation. github.com/pmd/pmd.github.io - Contains the landing page https://pmd.github.io github.com/pmd/build-tools - Contains the checkstyle rules we use github.com/pmd/pmd-eclipse-plugin...