Merge pull request #891 from linwumingshi/refactor/generic-javadoc-doc-template

enhance `IJavadocDocTemplate` with generics for method documentation

Author: shalousun

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());
-	}
-
 }