[java] Add grammar jdoc for new Record types

hirsute-chauve · Feb 28, 2020 · e2d84d6 · e2d84d6
1 parent 8a22446
commit e2d84d6
Show file tree

Hide file tree

Showing 11 changed files with 89 additions and 5 deletions.
diff --git a/pmd-java/etc/grammar/Java.jjt b/pmd-java/etc/grammar/Java.jjt
@@ -1174,7 +1174,7 @@ void RecordConstructorDeclaration():
   [TypeParameters()]
   Name()
   [ "throws" NameList() ]
-  [ "{" ( BlockStatement() )* "}" ]
+  "{" ( BlockStatement() )* "}"
 }
 
 void TypeParameters():

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTClassOrInterfaceDeclaration.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTClassOrInterfaceDeclaration.java
@@ -16,7 +16,7 @@
  * Represents class and interface declarations. This is a {@linkplain Node#isFindBoundary() find boundary}
  * for tree traversal methods.
  *
- * <pre>
+ * <pre class="grammar">
  *
  * ClassOrInterfaceDeclaration ::= ( "class" | "interface" )
  *                                 &lt;IDENTIFIER&gt;

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTPattern.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTPattern.java
@@ -16,7 +16,7 @@
  *
  * <p>See https://openjdk.java.net/jeps/305, https://openjdk.java.net/jeps/8235186
  *
- * <pre>
+ * <pre class="grammar">
  *
  * Pattern ::= {@link ASTTypeTestPattern TypeTestPattern}
  *

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordBody.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordBody.java
@@ -7,6 +7,17 @@
 
 import net.sourceforge.pmd.annotation.Experimental;
 
+/**
+ * Defines the body of a {@linkplain ASTRecordDeclaration RecordDeclaration} (JDK 14 preview feature).
+ * This can contain additional methods and or constructors.
+ *
+ * <pre class="grammar">
+ *
+ * RecordBody ::= "{" ({@linkplain ASTRecordBodyDeclaration RecordBodyDeclaration})* "}"
+ *
+ * </pre>
+ *
+ */
 @Experimental
 public class ASTRecordBody extends AbstractJavaNode {
     ASTRecordBody(int id) {

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordBodyDeclaration.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordBodyDeclaration.java
@@ -7,6 +7,19 @@
 
 import net.sourceforge.pmd.annotation.Experimental;
 
+/**
+ * This is part of {@linkplain ASTRecordDeclaration RecordDeclaration} (JDK 14 preview feature).
+ * It is can contain either a normal method or constructor or a compact
+ * {@linkplain ASTRecordConstructorDeclaration RecordConstructorDeclaration}.
+ *
+ * <pre class="grammar">
+ *
+ * RecordBodyDeclaration ::=   {@linkplain ASTRecordConstructorDeclaration RecordConstructorDeclaration}
+ *                           | {@linkplain ASTClassOrInterfaceBodyDeclaration ClassOrInterfaceBodyDeclaration}
+ *
+ * </pre>
+ *
+ */
 @Experimental
 public class ASTRecordBodyDeclaration extends AbstractJavaNode {
     ASTRecordBodyDeclaration(int id) {

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordComponent.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordComponent.java
@@ -7,6 +7,17 @@
 
 import net.sourceforge.pmd.annotation.Experimental;
 
+/**
+ * Defines a single component of a {@linkplain ASTRecordDeclaration RecordDeclaration} (JDK 14 preview feature).
+ *
+ * <pre class="grammar">
+ *
+ * RecordComponent ::= ({@linkplain ASTTypeAnnotation TypeAnnotation})*
+ *                     {@linkplain ASTType Type}
+ *                     &lt;IDENTIFIER&gt;
+ *
+ * </pre>
+ */
 @Experimental
 public class ASTRecordComponent extends AbstractJavaNode {
     ASTRecordComponent(int id) {

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordComponents.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordComponents.java
@@ -7,6 +7,15 @@
 
 import net.sourceforge.pmd.annotation.Experimental;
 
+/**
+ * Defines the state description of a {@linkplain ASTRecordDeclaration RecordDeclaration} (JDK 14 preview feature).
+ *
+ * <pre class="grammar">
+ *
+ * RecordComponents ::= {@linkplain ASTRecordComponent RecordComponent} ( "," {@linkplain ASTRecordComponent RecordComponent} )*
+ *
+ * </pre>
+ */
 @Experimental
 public class ASTRecordComponents extends AbstractJavaNode {
     ASTRecordComponents(int id) {

diff --git a/...java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordConstructorDeclaration.java b/...java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordConstructorDeclaration.java
@@ -7,6 +7,21 @@
 
 import net.sourceforge.pmd.annotation.Experimental;
 
+/**
+ * This defines a compact constructor for a {@linkplain ASTRecordDeclaration RecordDeclaration} (JDK 14 preview feature).
+ *
+ * <pre class="grammar">
+ *
+ * RecordConstructorDeclaration ::=  ({@linkplain ASTTypeAnnotation TypeAnnotation})*
+ *                                   {@linkplain ASTModifiers Modifiers}
+ *                                   {@linkplain ASTTypeParameters TypeParameters}?
+ *                                   {@linkplain ASTName Name}
+ *                                   ( "throws" {@linkplain ASTNameList NameList} )?
+ *                                   "{" ( {@linkplain ASTBlockStatement ASTBlockStatement} )* "}"
+ *
+ * </pre>
+ *
+ */
 @Experimental
 public class ASTRecordConstructorDeclaration extends AbstractJavaAccessNode {
     ASTRecordConstructorDeclaration(int id) {

diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordDeclaration.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/ASTRecordDeclaration.java
@@ -8,7 +8,25 @@
 import java.util.List;
 
 import net.sourceforge.pmd.annotation.Experimental;
-
+import net.sourceforge.pmd.lang.ast.Node;
+
+/**
+ * A record declaration is a special data class type (JDK 14 preview feature).
+ * This is a {@linkplain Node#isFindBoundary() find boundary} for tree traversal methods.
+ *
+ * <pre class="grammar">
+ *
+ * RecordDeclaration ::= "record"
+ *                       &lt;IDENTIFIER&gt;
+ *                       {@linkplain ASTTypeParameters TypeParameters}?
+ *                       "(" {@linkplain ASTRecordComponents RecordComponents} ")"
+ *                       {@linkplain ASTImplementsList ImplementsList}?
+ *                       {@linkplain ASTRecordBody RecordBody}
+ *
+ * </pre>
+ *
+ * @see <a href="https://openjdk.java.net/jeps/359">JEP 359: Records (Preview)</a>
+ */
 @Experimental
 public class ASTRecordDeclaration extends AbstractAnyTypeDeclaration {
     ASTRecordDeclaration(int id) {
@@ -34,4 +52,9 @@ public List<ASTAnyTypeBodyDeclaration> getDeclarations() {
         // TODO Auto-generated method stub
         return null;
     }
+
+    @Override
+    public boolean isFindBoundary() {
+        return isNested();
+    }
 }
diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/AbstractAnyTypeDeclaration.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/AbstractAnyTypeDeclaration.java
@@ -33,7 +33,8 @@ public abstract class AbstractAnyTypeDeclaration extends AbstractJavaAccessTypeN
     @Override
     public final boolean isNested() {
         return getParent() instanceof ASTClassOrInterfaceBodyDeclaration
-            || getParent() instanceof ASTAnnotationTypeMemberDeclaration;
+            || getParent() instanceof ASTAnnotationTypeMemberDeclaration
+            || getParent() instanceof ASTRecordBodyDeclaration;
     }
 
     @Override

diff --git a/.../src/test/resources/net/sourceforge/pmd/lang/java/ast/jdkversiontests/java14/Records.java b/.../src/test/resources/net/sourceforge/pmd/lang/java/ast/jdkversiontests/java14/Records.java
@@ -5,6 +5,7 @@ public class Records {
 
 
     public record MyComplex(int real, int imaginary) {
+        public record Nested(int a) {};
     };
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,7 +16,7 @@ @@
      *
      * <p>See https://openjdk.java.net/jeps/305, https://openjdk.java.net/jeps/8235186
      *
-     * <pre>
+     * <pre class="grammar">
      *
      * Pattern ::= {@link ASTTypeTestPattern TypeTestPattern}
      *
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,6 +5,7 @@ public class Records {


		public record MyComplex(int real, int imaginary) {
		public record Nested(int a) {};
		};


Expand Down