refactor: ♻️ enhance IJavadocDocTemplate with generics for method documentation

Refactored the `IJavadocDocTemplate` interface to support generics, improving flexibility in handling Java method documentation. This change includes the removal of deprecated templates and the addition of new methods to better support RPC documentation generation.

BREAKING CHANGE: Existing implementations of `IJavadocDocTemplate` and `IDocBuildTemplate` need to be updated to accommodate the new method signatures and class structures.

Author: linwumingshi

src/main/java/com/ly/doc/template/GRpcDocBuildTemplate.java

@@ -1,3 +1,23 @@
+/*
+ * Copyright (C) 2018-2024 smart-doc
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
 package com.ly.doc.template;
 
 import com.google.gson.Gson;
@@ -36,8 +56,9 @@
  * gRPC Doc build template.
  *
  * @author linwumingshi
+ * @since 3.0.7
  */
-public class GRpcDocBuildTemplate implements IDocBuildTemplate<GrpcApiDoc>, IRpcDocTemplate {
+public class GRpcDocBuildTemplate implements IDocBuildTemplate<GrpcApiDoc>, IJavadocDocTemplate<GrpcJavaMethod> {
 
 	/**
 	 * Logger for the class.
@@ -69,6 +90,11 @@ public boolean addMethodModifiers() {
 		return false;
 	}
 
+	@Override
+	public GrpcJavaMethod createEmptyJavadocJavaMethod() {
+		return new GrpcJavaMethod();
+	}
+
 	@Override
 	public boolean ignoreReturnObject(String typeName, List<String> ignoreParams) {
 		return false;

src/main/java/com/ly/doc/template/IJavadocDocTemplate.java

@@ -39,25 +39,37 @@
 import static com.ly.doc.constants.DocTags.DEPRECATED;
 import static com.ly.doc.constants.DocTags.IGNORE;
 
-public interface IJavadocDocTemplate extends IBaseDocBuildTemplate {
+/**
+ * java doc template
+ *
+ * @param <T> extends JavadocJavaMethod
+ * @author shalousun
+ * @since 3.0.5
+ */
+public interface IJavadocDocTemplate<T extends JavadocJavaMethod> extends IBaseDocBuildTemplate {
 
 	/**
 	 * Add method modifiers
 	 * @return boolean
 	 */
 	boolean addMethodModifiers();
 
+	/**
+	 * Create empty JavadocJavaMethod.
+	 * @return empty JavadocJavaMethod
+	 */
+	T createEmptyJavadocJavaMethod();
+
 	/**
 	 * Convert JavaMethod to JavadocJavaMethod
 	 * @param apiConfig ApiConfig
 	 * @param method JavaMethod
 	 * @param actualTypesMap Map
 	 * @return JavadocJavaMethod
 	 */
-	default JavadocJavaMethod convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMethod method,
-			Map<String, JavaType> actualTypesMap) {
+	default T convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMethod method, Map<String, JavaType> actualTypesMap) {
 		JavaClass cls = method.getDeclaringClass();
-		JavadocJavaMethod javadocJavaMethod = new JavadocJavaMethod();
+		T javadocJavaMethod = this.createEmptyJavadocJavaMethod();
 		javadocJavaMethod.setJavaMethod(method);
 		javadocJavaMethod.setName(method.getName());
 		javadocJavaMethod.setActualTypesMap(actualTypesMap);
@@ -108,7 +120,7 @@ default String methodDefinition(JavaMethod method, Map<String, JavaType> actualT
 			// append method modifiers
 			method.getModifiers().forEach(item -> methodBuilder.append(item).append(" "));
 		}
-		String returnType = getMethodReturnType(method, actualTypesMap);
+		String returnType = this.getMethodReturnType(method, actualTypesMap);
 		// append method return type
 		methodBuilder.append(returnType).append(" ");
 		List<String> params = new ArrayList<>();
@@ -122,47 +134,54 @@ default String methodDefinition(JavaMethod method, Map<String, JavaType> actualT
 	}
 
 	/**
-	 * Get parent class methods
-	 * @param apiConfig ApiConfig
+	 * Processes methods of a given class and its parent or interfaces.
 	 * @param cls JavaClass
-	 * @return List
+	 * @param methodProcessor Function to process methods from a class
+	 * @return List of documented Java methods
 	 */
-	default List<? extends JavadocJavaMethod> getParentsClassMethods(ApiConfig apiConfig, JavaClass cls) {
-		List<JavadocJavaMethod> docJavaMethods = new ArrayList<>();
-		JavaClass parentClass = cls.getSuperJavaClass();
-		// if parent class is not null and not Object
-		if (Objects.nonNull(parentClass) && !JavaTypeConstants.OBJECT_SIMPLE_NAME.equals(parentClass.getSimpleName())) {
-			Map<String, JavaType> actualTypesMap = JavaClassUtil.getActualTypesMap(parentClass);
-			List<JavaMethod> parentMethodList = parentClass.getMethods();
-			for (JavaMethod method : parentMethodList) {
-				docJavaMethods.add(this.convertToJavadocJavaMethod(apiConfig, method, actualTypesMap));
+	default List<T> processClassHierarchy(JavaClass cls, Function<JavaClass, List<T>> methodProcessor) {
+		List<T> docJavaMethods = new ArrayList<>();
+		Set<JavaClass> classesToProcess = new LinkedHashSet<>();
+		classesToProcess.add(cls);
+
+		while (!classesToProcess.isEmpty()) {
+			JavaClass currentClass = classesToProcess.iterator().next();
+			classesToProcess.remove(currentClass);
+
+			// Process methods
+			docJavaMethods.addAll(methodProcessor.apply(currentClass));
+
+			// Add parent class if not Object
+			JavaClass parentClass = currentClass.getSuperJavaClass();
+			if (Objects.nonNull(parentClass)
+					&& !JavaTypeConstants.OBJECT_SIMPLE_NAME.equals(parentClass.getSimpleName())) {
+				classesToProcess.add(parentClass);
 			}
-			// add interface methods
-			docJavaMethods.addAll(this.getInterfaceMethods(apiConfig, parentClass));
-			// add parent class methods
-			docJavaMethods.addAll(this.getParentsClassMethods(apiConfig, parentClass));
+
+			// Add interfaces
+			classesToProcess.addAll(currentClass.getInterfaces());
 		}
+
 		return docJavaMethods;
 	}
 
 	/**
-	 * Get interface methods
+	 * Get parent class and interface methods
 	 * @param apiConfig ApiConfig
 	 * @param cls JavaClass
 	 * @return List
 	 */
-	default List<? extends JavadocJavaMethod> getInterfaceMethods(ApiConfig apiConfig, JavaClass cls) {
-		List<JavadocJavaMethod> docJavaMethods = new ArrayList<>();
-		for (JavaClass javaInterface : cls.getInterfaces()) {
-			Map<String, JavaType> actualTypesMap = JavaClassUtil.getActualTypesMap(javaInterface);
-			List<JavaMethod> interfaceMethodList = javaInterface.getMethods();
-			for (JavaMethod method : interfaceMethodList) {
+	default List<T> getParentsClassAndInterfaceMethods(ApiConfig apiConfig, JavaClass cls) {
+		return this.processClassHierarchy(cls, currentClass -> {
+			List<T> docJavaMethods = new ArrayList<>();
+			Map<String, JavaType> actualTypesMap = JavaClassUtil.getActualTypesMap(currentClass);
+			List<JavaMethod> methodList = currentClass.getMethods();
+			for (JavaMethod method : methodList) {
 				docJavaMethods.add(this.convertToJavadocJavaMethod(apiConfig, method, actualTypesMap));
 			}
-			// add interface methods
-			docJavaMethods.addAll(this.getInterfaceMethods(apiConfig, javaInterface));
-		}
-		return docJavaMethods;
+			return docJavaMethods;
+		});
+
 	}
 
 	/**
@@ -301,11 +320,11 @@ else if (javaClass.isEnum()) {
 	 * @return A list containing documented methods represented as JavadocJavaMethod
 	 * objects.
 	 */
-	default List<? extends JavadocJavaMethod> buildServiceMethod(final JavaClass cls, ApiConfig apiConfig,
+	default List<T> buildServiceMethod(final JavaClass cls, ApiConfig apiConfig,
 			ProjectDocConfigBuilder projectBuilder) {
 		String clsCanonicalName = cls.getCanonicalName();
 		List<JavaMethod> methods = cls.getMethods();
-		List<JavadocJavaMethod> methodDocList = new ArrayList<>(methods.size());
+		List<T> methodDocList = new ArrayList<>(methods.size());
 
 		Set<String> filterMethods = DocUtil.findFilterMethods(clsCanonicalName);
 		boolean needAllMethods = filterMethods.contains(DocGlobalConstants.DEFAULT_FILTER_METHOD);
@@ -322,21 +341,19 @@ default List<? extends JavadocJavaMethod> buildServiceMethod(final JavaClass cls
 						"Unable to find comment for method " + method.getName() + " in " + cls.getCanonicalName());
 			}
 			if (needAllMethods || filterMethods.contains(method.getName())) {
-				JavadocJavaMethod apiMethodDoc = this.convertToJavadocJavaMethod(apiConfig, method, null);
+				T apiMethodDoc = this.convertToJavadocJavaMethod(apiConfig, method, null);
 				methodDocList.add(apiMethodDoc);
 			}
 
 		}
-		// Add parent class methods
-		methodDocList.addAll(this.getParentsClassMethods(apiConfig, cls));
-		// Add interface methods
-		methodDocList.addAll(this.getInterfaceMethods(apiConfig, cls));
+		// Add parent class And interface methods
+		methodDocList.addAll(this.getParentsClassAndInterfaceMethods(apiConfig, cls));
 
-		Map<JavadocJavaMethod, List<ApiParam>> methodRequestParams = new HashMap<>(16);
-		Map<JavadocJavaMethod, List<ApiParam>> methodResponseParams = new HashMap<>(16);
+		Map<T, List<ApiParam>> methodRequestParams = new HashMap<>(16);
+		Map<T, List<ApiParam>> methodResponseParams = new HashMap<>(16);
 
 		// Construct the method map
-		Map<String, JavadocJavaMethod> methodMap = methodDocList.stream().collect(Collectors.toMap(method -> {
+		Map<String, T> methodMap = methodDocList.stream().collect(Collectors.toMap(method -> {
 			// Build request params
 			List<ApiParam> requestParams = this.requestParams(method.getJavaMethod(), projectBuilder,
 					new AtomicInteger(0), method.getActualTypesMap());
@@ -357,8 +374,8 @@ default List<? extends JavadocJavaMethod> buildServiceMethod(final JavaClass cls
 				Function.identity(), this::mergeJavadocMethods, LinkedHashMap::new));
 
 		int methodOrder = 0;
-		List<JavadocJavaMethod> javadocJavaMethods = new ArrayList<>(methodMap.values().size());
-		for (JavadocJavaMethod method : methodMap.values()) {
+		List<T> javadocJavaMethods = new ArrayList<>(methodMap.values().size());
+		for (T method : methodMap.values()) {
 			methodOrder++;
 			method.setOrder(methodOrder);
 			String methodUid = DocUtil.generateId(clsCanonicalName + method.getName() + methodOrder);
@@ -389,7 +406,7 @@ default List<? extends JavadocJavaMethod> buildServiceMethod(final JavaClass cls
 	 * @return The merged JavadocJavaMethod object, with details filled in from the
 	 * replacement method if necessary.
 	 */
-	default JavadocJavaMethod mergeJavadocMethods(JavadocJavaMethod existing, JavadocJavaMethod replacement) {
+	default T mergeJavadocMethods(T existing, T replacement) {
 		// if existing info is empty and replacement info has desc,replace the info
 		if (StringUtil.isEmpty(existing.getDesc()) && StringUtil.isNotEmpty(replacement.getDesc())) {
 			existing.setDesc(replacement.getDesc());

src/main/java/com/ly/doc/template/IRpcDocTemplate.java

@@ -65,6 +65,11 @@ public boolean addMethodModifiers() {
 		return true;
 	}
 
+	@Override
+	public JavadocJavaMethod createEmptyJavadocJavaMethod() {
+		return new JavadocJavaMethod();
+	}
+
 	@Override
 	@SuppressWarnings("unchecked")
 	public ApiSchema<JavadocApiDoc> renderApi(ProjectDocConfigBuilder projectBuilder,

src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java

@@ -24,14 +24,20 @@
 import com.ly.doc.constants.DocTags;
 import com.ly.doc.constants.DubboAnnotationConstants;
 import com.ly.doc.constants.FrameworkEnum;
-import com.ly.doc.model.*;
+import com.ly.doc.model.ApiConfig;
+import com.ly.doc.model.ApiSchema;
+import com.ly.doc.model.RpcJavaMethod;
+import com.ly.doc.model.WebSocketDoc;
 import com.ly.doc.model.annotation.FrameworkAnnotations;
 import com.ly.doc.model.rpc.RpcApiDoc;
 import com.ly.doc.utils.DocUtil;
 import com.ly.doc.utils.JavaClassUtil;
 import com.power.common.util.StringUtil;
 import com.power.common.util.ValidateUtil;
-import com.thoughtworks.qdox.model.*;
+import com.thoughtworks.qdox.model.DocletTag;
+import com.thoughtworks.qdox.model.JavaAnnotation;
+import com.thoughtworks.qdox.model.JavaClass;
+import com.thoughtworks.qdox.model.JavaType;
 import com.thoughtworks.qdox.model.expression.AnnotationValue;
 
 import java.util.*;
@@ -43,8 +49,8 @@
  *
  * @author yu 2020/1/29.
  */
-public class RpcDocBuildTemplate
-		implements IDocBuildTemplate<RpcApiDoc>, IWebSocketDocBuildTemplate<WebSocketDoc>, IRpcDocTemplate {
+public class RpcDocBuildTemplate implements IDocBuildTemplate<RpcApiDoc>, IWebSocketDocBuildTemplate<WebSocketDoc>,
+		IJavadocDocTemplate<RpcJavaMethod> {
 
 	/**
 	 * api index
@@ -62,7 +68,11 @@ public boolean addMethodModifiers() {
 	}
 
 	@Override
-	@SuppressWarnings("unchecked")
+	public RpcJavaMethod createEmptyJavadocJavaMethod() {
+		return new RpcJavaMethod();
+	}
+
+	@Override
 	public ApiSchema<RpcApiDoc> renderApi(ProjectDocConfigBuilder projectBuilder,
 			Collection<JavaClass> candidateClasses) {
 		ApiConfig apiConfig = projectBuilder.getApiConfig();
@@ -81,8 +91,7 @@ public ApiSchema<RpcApiDoc> renderApi(ProjectDocConfigBuilder projectBuilder,
 				setCustomOrder = true;
 				maxOrder = Math.max(maxOrder, order);
 			}
-			List<RpcJavaMethod> apiMethodDocs = (List<RpcJavaMethod>) this.buildServiceMethod(cls, apiConfig,
-					projectBuilder);
+			List<RpcJavaMethod> apiMethodDocs = this.buildServiceMethod(cls, apiConfig, projectBuilder);
 			this.handleJavaApiDoc(cls, apiDocList, apiMethodDocs, order, projectBuilder);
 		}
 		ApiSchema<RpcApiDoc> apiSchema = new ApiSchema<>();
@@ -222,25 +231,4 @@ private void handleJavaApiDoc(JavaClass cls, List<RpcApiDoc> apiDocList, List<Rp
 		apiDocList.add(apiDoc);
 	}
 
-	@Override
-	public JavadocJavaMethod convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMethod method,
-			Map<String, JavaType> actualTypesMap) {
-		JavadocJavaMethod javaMethod = IRpcDocTemplate.super.convertToJavadocJavaMethod(apiConfig, method,
-				actualTypesMap);
-		return new RpcJavaMethod().setDetail(javaMethod.getDetail())
-			.setAuthor(javaMethod.getAuthor())
-			.setMethodDefinition(javaMethod.getMethodDefinition())
-			.setOrder(javaMethod.getOrder())
-			.setRequestParams(javaMethod.getRequestParams())
-			.setResponseParams(javaMethod.getResponseParams())
-			.setDeprecated((javaMethod.isDeprecated()))
-			.setVersion((javaMethod.getVersion()))
-			.setActualTypesMap(javaMethod.getActualTypesMap())
-			.setName(javaMethod.getName())
-			.setEscapeMethodDefinition(javaMethod.getEscapeMethodDefinition())
-			.setMethodId(javaMethod.getMethodId())
-			.setJavaMethod(javaMethod.getJavaMethod())
-			.setReturnClassInfo(javaMethod.getReturnClassInfo());
-	}
-
 }