more improvements to generated Javadoc in Hibernate Processor

gavinking · gavinking · commit 354419e2ddca · 2024-10-02T19:53:25.000+02:00
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/ClassWriter.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/ClassWriter.java
@@ -103,7 +103,8 @@ private static StringBuffer generateBody(Metamodel entity, Context context) {
 			final List<MetaAttribute> members = entity.getMembers();
 			for ( MetaAttribute metaMember : members ) {
 				if ( metaMember.hasStringAttribute() ) {
-					pw.println( '\t' + metaMember.getAttributeNameDeclarationString() );
+					metaMember.getAttributeNameDeclarationString().lines()
+							.forEach(line -> pw.println('\t' + line));
 				}
 			}
 
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/ImportContextImpl.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/ImportContextImpl.java
@@ -150,7 +150,7 @@ private String importTypes(String originalArgList) {
 		StringBuilder acc = new StringBuilder();
 		StringTokenizer args = new StringTokenizer( originalArgList, "," );
 		while ( args.hasMoreTokens() ) {
-			if ( acc.length() > 0 ) {
+			if ( !acc.isEmpty() ) {
 				acc.append( ',' );
 			}
 			acc.append( args.nextToken() );
@@ -166,7 +166,7 @@ private String importTypes(String originalArgList) {
 				}
 			}
 			if ( nesting == 0 ) {
-				if ( argList.length() > 0 ) {
+				if ( !argList.isEmpty() ) {
 					argList.append(',');
 				}
 				argList.append( importType( acc.toString() ) );
@@ -177,16 +177,10 @@ private String importTypes(String originalArgList) {
 	}
 
 	public String staticImport(String fqcn, String member) {
-		String local = fqcn + "." + member;
+		final String local = fqcn + "." + member;
 		imports.add( local );
 		staticImports.add( local );
-
-		if ( member.equals( "*" ) ) {
-			return "";
-		}
-		else {
-			return member;
-		}
+		return "*".equals(member) ? "" : member;
 	}
 
 	private boolean inDefaultPackage(String className) {
@@ -206,8 +200,7 @@ private boolean inJavaLang(String className) {
 	}
 
 	public String generateImports() {
-		StringBuilder builder = new StringBuilder();
-
+		final StringBuilder builder = new StringBuilder();
 		for ( String next : imports ) {
 			// don't add automatically "imported" stuff
 			if ( !isAutoImported( next ) ) {
@@ -219,15 +212,14 @@ public String generateImports() {
 				}
 			}
 		}
-
-		if ( builder.indexOf( "$" ) >= 0 ) {
-			return builder.toString();
-		}
 		return builder.toString();
 	}
 
 	private boolean isAutoImported(String next) {
-		return isPrimitive( next ) || inDefaultPackage( next ) || inJavaLang( next ) || inSamePackage( next );
+		return isPrimitive( next )
+			|| inDefaultPackage( next )
+			|| inJavaLang( next )
+			|| inSamePackage( next );
 	}
 
 	public static String unqualify(String qualifiedName) {
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractFinderMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractFinderMethod.java
@@ -5,14 +5,11 @@
 package org.hibernate.processor.annotation;
 
 import org.checkerframework.checker.nullness.qual.Nullable;
-import org.hibernate.internal.util.StringHelper;
 
 import javax.lang.model.element.ExecutableElement;
 import java.util.List;
-import java.util.Locale;
 
 import static org.hibernate.processor.util.Constants.HIB_SESSION;
-import static org.hibernate.processor.util.StringUtil.getUpperUnderscoreCaseFromLowerCamelCase;
 
 /**
  * @author Gavin King
@@ -70,27 +67,7 @@ public String getTypeDeclaration() {
 
 	@Override
 	public String getAttributeNameDeclarationString() {
-		return new StringBuilder()
-				.append("public static final String ")
-				.append(constantName())
-				.append(" = \"!")
-				.append(annotationMetaEntity.getQualifiedName())
-				.append('.')
-				.append(methodName)
-				.append("(")
-				.append(parameterList())
-				.append(")")
-				.append("\";")
-				.toString();
-	}
-
-	String constantName() {
-		return getUpperUnderscoreCaseFromLowerCamelCase(methodName) + "_BY_"
-				+ paramNames.stream()
-				.map(StringHelper::unqualify)
-				.map(name -> name.toUpperCase(Locale.ROOT))
-				.reduce((x,y) -> x + "_AND_" + y)
-				.orElse("");
+		throw new UnsupportedOperationException("operation not supported");
 	}
 
 	void comment(StringBuilder declaration) {
@@ -188,20 +165,6 @@ void tryReturn(StringBuilder declaration) {
 				.append(sessionName);
 	}
 
-//	private void returnType(StringBuilder declaration) {
-//		if ( isReactive() ) {
-//			declaration
-//					.append(annotationMetaEntity.importType(UNI))
-//					.append('<');
-//		}
-//		declaration
-//				.append(annotationMetaEntity.importType(entity));
-//		if ( isReactive() ) {
-//			declaration
-//					.append('>');
-//		}
-//	}
-
 	void modifiers(StringBuilder declaration) {
 		declaration
 				.append(belongsToDao ? "@Override\npublic " : "public static ");
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractQueryMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AbstractQueryMethod.java
@@ -105,10 +105,21 @@ String parameterList() {
 				.orElse("");
 	}
 
-	String strip(String type) {
-		int index = type.indexOf("<");
-		String stripped = index > 0 ? type.substring(0, index) : type;
-		return type.endsWith("...") ? stripped + "..." : stripped;
+	String strip(final String fullType) {
+		String type = fullType;
+		// strip off type annotations
+		while ( type.charAt(0) == '@' ) {
+			int startIndex = type.indexOf( ' ' );
+			if ( startIndex > 0 ) {
+				type = type.substring(startIndex+1);
+			}
+		}
+		// strip off type arguments
+		int endIndex = type.indexOf("<");
+		if ( endIndex > 0 ) {
+			type = type.substring(0, endIndex);
+		}
+		return fullType.endsWith("...") ? type + "..." : type;
 	}
 
 	void preamble(StringBuilder declaration, List<String> paramTypes) {
@@ -175,7 +186,12 @@ void see(StringBuilder declaration) {
 		declaration
 				.append("\n * @see ")
 				.append(annotationMetaEntity.getQualifiedName())
-				.append("#")
+				.append("#");
+		signature(declaration);
+	}
+
+	void signature(StringBuilder declaration) {
+		declaration
 				.append(methodName)
 				.append("(")
 				.append(parameterList())
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaAttribute.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaAttribute.java
@@ -44,11 +44,11 @@ public boolean hasStringAttribute() {
 	@Override
 	public String getAttributeDeclarationString() {
 		return new StringBuilder()
-				.append("\n/**\n * @see ")
+				.append("\n/**\n * Static metamodel for attribute {@link ")
 				.append(parent.getQualifiedName())
 				.append('#')
 				.append(element.getSimpleName())
-				.append("\n **/\n")
+				.append("}\n **/\n")
 				.append("public static volatile ")
 				.append(parent.importType(getMetaType()))
 				.append('<')
@@ -65,6 +65,10 @@ public String getAttributeDeclarationString() {
 	@Override
 	public String getAttributeNameDeclarationString(){
 		return new StringBuilder()
+				.append("\n/**\n * @see ")
+				.append("#")
+				.append(getPropertyName())
+				.append( "\n **/\n" )
 				.append("public static final ")
 				.append(parent.importType(String.class.getName()))
 				.append(' ')
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaMap.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaMap.java
@@ -24,11 +24,11 @@ public AnnotationMetaMap(AnnotationMetaEntity parent, Element element, String co
 	@Override
 	public String getAttributeDeclarationString() {
 		return new StringBuilder()
-				.append("\n/**\n * @see ")
+				.append("\n/**\n * Static metamodel for attribute {@link ")
 				.append( parent.getQualifiedName() )
 				.append("#")
 				.append( element.getSimpleName() )
-				.append("\n **/\n")
+				.append("}\n **/\n")
 				.append("public static volatile ")
 				.append( parent.importType( getMetaType() ) )
 				.append("<")
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaType.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/AnnotationMetaType.java
@@ -35,9 +35,9 @@ public boolean hasStringAttribute() {
 	@Override
 	public String getAttributeDeclarationString() {
 		return new StringBuilder()
-				.append("\n/**\n * @see ")
+				.append("\n/**\n * Static metamodel type for {@link ")
 				.append( annotationMetaEntity.getQualifiedName() )
-				.append( "\n **/\n" )
+				.append( "}\n **/\n" )
 				.append("public static volatile ")
 				.append(annotationMetaEntity.importType(getTypeDeclaration()))
 				.append("<")
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/DataAnnotationMetaAttribute.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/DataAnnotationMetaAttribute.java
@@ -56,12 +56,11 @@ public String getAttributeDeclarationString() {
 				? parent.importType("jakarta.data.metamodel.impl.TextAttributeRecord")
 				: parent.importType("jakarta.data.metamodel.impl.SortableAttributeRecord");
 		return new StringBuilder()
-				.append("\n/**\n * @see ")
+				.append("\n/**\n * Static metamodel for attribute {@link ")
 				.append(className)
-				.append( "#")
+				.append("#")
 				.append(memberName)
-				.append( "\n **/\n" )
-//				.append( "public static final " )
+				.append( "}\n **/\n" )
 				.append( parent.importType( getMetaType() ) )
 				.append( "<" )
 				.append( className )
@@ -78,7 +77,10 @@ public String getAttributeDeclarationString() {
 	@Override
 	public String getAttributeNameDeclarationString(){
 		return new StringBuilder()
-//				.append("public static final ")
+				.append("\n/**\n * @see ")
+				.append("#")
+				.append( getPropertyName().replace('.','_') )
+				.append( "\n **/\n" )
 				.append(parent.importType(String.class.getName()))
 				.append(" ")
 				.append(fieldName())
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/QueryMethod.java
@@ -268,31 +268,37 @@ private void modifiers(List<String> paramTypes, StringBuilder declaration) {
 
 	@Override
 	public String getAttributeNameDeclarationString() {
-		StringBuilder sb = new StringBuilder(queryString.length() + 100)
+		StringBuilder declaration = new StringBuilder( queryString.length() + 200 );
+		declaration
+				.append("\n/**\n * @see ")
+				.append("#");
+		signature( declaration );
+		declaration
+				.append( "\n **/\n" )
 				.append( "static final String " )
 				.append( getConstantName() )
 				.append( " = \"" );
 		for ( int i = 0; i < queryString.length(); i++ ) {
 			final char c = queryString.charAt( i );
 			switch ( c ) {
 				case '\r':
-					sb.append( "\\r" );
+					declaration.append( "\\r" );
 					break;
 				case '\n':
-					sb.append( "\\n" );
+					declaration.append( "\\n" );
 					break;
 				case '\\':
-					sb.append( "\\\\" );
+					declaration.append( "\\\\" );
 					break;
 				case '"':
-					sb.append( "\\\"" );
+					declaration.append( "\\\"" );
 					break;
 				default:
-					sb.append( c );
+					declaration.append( c );
 					break;
 			}
 		}
-		return sb.append("\";").toString();
+		return declaration.append("\";").toString();
 	}
 
 	private String getConstantName() {
diff --git a/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/TypedMetaAttribute.java b/tooling/metamodel-generator/src/main/java/org/hibernate/processor/annotation/TypedMetaAttribute.java
@@ -39,9 +39,26 @@ public boolean hasTypedAttribute() {
 		return true;
 	}
 
+	private boolean isQuery() {
+		return "QUERY_".equals(prefix);  //UGLY!
+	}
+
+	@Override
+	public String getAttributeNameDeclarationString() {
+		StringBuilder declaration = new StringBuilder();
+		declaration
+				.append("\n/**\n * @see ")
+				.append("#");
+		appendFieldName( declaration, isQuery() );
+		return declaration
+				.append( "\n **/\n" )
+				.append(super.getAttributeNameDeclarationString())
+				.toString();
+	}
+
 	@Override
 	public String getAttributeDeclarationString() {
-		final boolean isQuery = "QUERY_".equals(prefix);  //UGLY!
+		final boolean isQuery = isQuery();
 		final Metamodel entity = getHostingEntity();
 		final StringBuilder declaration = new StringBuilder();
 		declaration
@@ -67,13 +84,18 @@ public String getAttributeDeclarationString() {
 				.append('<')
 				.append(entity.importType(resultType))
 				.append('>')
-				.append(' ')
+				.append(' ');
+		appendFieldName( declaration, isQuery );
+		declaration.append(';');
+		return declaration.toString();
+	}
+
+	private void appendFieldName(StringBuilder declaration, boolean isQuery) {
+		declaration
 				.append('_')
 				.append(nameToMethodName(getPropertyName()));
 		if ( isQuery ) {
 			declaration.append('_');
 		}
-		declaration.append(';');
-		return declaration.toString();
 	}
 }

Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,8 @@ private static StringBuffer generateBody(Metamodel entity, Context context) {`
`103`	`103`	`final List<MetaAttribute> members = entity.getMembers();`
`104`	`104`	`for ( MetaAttribute metaMember : members ) {`
`105`	`105`	`if ( metaMember.hasStringAttribute() ) {`
`106`		`- pw.println( '\t' + metaMember.getAttributeNameDeclarationString() );`
	`106`	`+ metaMember.getAttributeNameDeclarationString().lines()`
	`107`	`+ .forEach(line -> pw.println('\t' + line));`
`107`	`108`	`}`
`108`	`109`	`}`
`109`	`110`
Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,7 @@ private String importTypes(String originalArgList) {`
`150`	`150`	`StringBuilder acc = new StringBuilder();`
`151`	`151`	`StringTokenizer args = new StringTokenizer( originalArgList, "," );`
`152`	`152`	`while ( args.hasMoreTokens() ) {`
`153`		`- if ( acc.length() > 0 ) {`
	`153`	`+ if ( !acc.isEmpty() ) {`
`154`	`154`	`acc.append( ',' );`
`155`	`155`	`}`
`156`	`156`	`acc.append( args.nextToken() );`
`@@ -166,7 +166,7 @@ private String importTypes(String originalArgList) {`
`166`	`166`	`}`
`167`	`167`	`}`
`168`	`168`	`if ( nesting == 0 ) {`
`169`		`- if ( argList.length() > 0 ) {`
	`169`	`+ if ( !argList.isEmpty() ) {`
`170`	`170`	`argList.append(',');`
`171`	`171`	`}`
`172`	`172`	`argList.append( importType( acc.toString() ) );`
`@@ -177,16 +177,10 @@ private String importTypes(String originalArgList) {`
`177`	`177`	`}`
`178`	`178`
`179`	`179`	`public String staticImport(String fqcn, String member) {`
`180`		`- String local = fqcn + "." + member;`
	`180`	`+ final String local = fqcn + "." + member;`
`181`	`181`	`imports.add( local );`
`182`	`182`	`staticImports.add( local );`
`183`		`-`
`184`		`- if ( member.equals( "*" ) ) {`
`185`		`- return "";`
`186`		`- }`
`187`		`- else {`
`188`		`- return member;`
`189`		`- }`
	`183`	`+ return "*".equals(member) ? "" : member;`
`190`	`184`	`}`
`191`	`185`
`192`	`186`	`private boolean inDefaultPackage(String className) {`
`@@ -206,8 +200,7 @@ private boolean inJavaLang(String className) {`
`206`	`200`	`}`
`207`	`201`
`208`	`202`	`public String generateImports() {`
`209`		`- StringBuilder builder = new StringBuilder();`
`210`		`-`
	`203`	`+ final StringBuilder builder = new StringBuilder();`
`211`	`204`	`for ( String next : imports ) {`
`212`	`205`	`// don't add automatically "imported" stuff`
`213`	`206`	`if ( !isAutoImported( next ) ) {`
`@@ -219,15 +212,14 @@ public String generateImports() {`
`219`	`212`	`}`
`220`	`213`	`}`
`221`	`214`	`}`
`222`		`-`
`223`		`- if ( builder.indexOf( "$" ) >= 0 ) {`
`224`		`- return builder.toString();`
`225`		`- }`
`226`	`215`	`return builder.toString();`
`227`	`216`	`}`
`228`	`217`
`229`	`218`	`private boolean isAutoImported(String next) {`
`230`		`- return isPrimitive( next ) \|\| inDefaultPackage( next ) \|\| inJavaLang( next ) \|\| inSamePackage( next );`
	`219`	`+ return isPrimitive( next )`
	`220`	`+ \|\| inDefaultPackage( next )`
	`221`	`+ \|\| inJavaLang( next )`
	`222`	`+ \|\| inSamePackage( next );`
`231`	`223`	`}`
`232`	`224`
`233`	`225`	`public static String unqualify(String qualifiedName) {`