Enhancement for docprocessor (#5028)
Co-authored-by: jm041977 <john.marquez@broadcom.com>
diff --git a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessor.java b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessor.java
index 3f10dc8..feb1f43 100644
--- a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessor.java
+++ b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessor.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2022 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
@@ -16,6 +16,7 @@
package org.glassfish.jersey.wadl.doclet;
+import jdk.javadoc.doclet.DocletEnvironment;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.ClassDocType;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.MethodDocType;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.ParamDocType;
@@ -60,6 +61,7 @@
* @param classDocType the {@link ClassDocType} to extend. This will later be processed by the
* {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
*/
+ @Deprecated
void processClassDoc(TypeElement classDoc, ClassDocType classDocType);
/**
@@ -69,6 +71,7 @@
* @param methodDocType the related {@link MethodDocType} that will later be processed by the
* {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
*/
+ @Deprecated
void processMethodDoc(ExecutableElement methodDoc, MethodDocType methodDocType);
/**
@@ -79,6 +82,45 @@
* @param paramDocType the {@link ParamDocType} to extend. This will later be processed by the
* {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
*/
+ @Deprecated
void processParamTag(VariableElement parameter, ParamDocType paramDocType);
+ /**
+ * Use this method to extend the provided {@link ClassDocType} with the information from
+ * the given {@link TypeElement}.
+ *
+ * @param classDoc the class javadoc
+ * @param classDocType the {@link ClassDocType} to extend. This will later be processed by the
+ * {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
+ * @param docEnv the doclet environment used to extract info from classDoc
+ */
+ default void processClassDocWithDocEnv(TypeElement classDoc, ClassDocType classDocType, DocletEnvironment docEnv) {
+ processClassDoc(classDoc, classDocType);
+ }
+
+ /**
+ * Process the provided methodDoc and add your custom information to the methodDocType.<br>
+ *
+ * @param methodDoc the {@link ExecutableElement} representing the docs of your method.
+ * @param methodDocType the related {@link MethodDocType} that will later be processed by the
+ * {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
+ * @param docEnv the doclet environment used to extract info from methodDoc
+ */
+ default void processMethodDocWithDocEnv(ExecutableElement methodDoc, MethodDocType methodDocType, DocletEnvironment docEnv) {
+ processMethodDoc(methodDoc, methodDocType);
+ }
+
+ /**
+ * Use this method to extend the provided {@link ParamDocType} with the information from the
+ * given {@link VariableElement}.
+ *
+ * @param parameter the parameter (that is documented or not)
+ * @param paramDocType the {@link ParamDocType} to extend. This will later be processed by the
+ * {@link org.glassfish.jersey.server.wadl.WadlGenerator}s.
+ * @param docEnv the Doclet Environment used to extract info from parameter
+ */
+ default void processParamTagWithDocEnv(VariableElement parameter, ParamDocType paramDocType, DocletEnvironment docEnv) {
+ processParamTag(parameter, paramDocType);
+ }
+
}
diff --git a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessorWrapper.java b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessorWrapper.java
index aa3e28d..03407db 100644
--- a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessorWrapper.java
+++ b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessorWrapper.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2022 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
@@ -20,13 +20,13 @@
import java.util.Arrays;
import java.util.List;
+import jdk.javadoc.doclet.DocletEnvironment;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.ClassDocType;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.MethodDocType;
import org.glassfish.jersey.server.wadl.internal.generators.resourcedoc.model.ParamDocType;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.ExecutableElement;
-import com.sun.source.doctree.ParamTree;
import javax.lang.model.element.VariableElement;
public class DocProcessorWrapper implements DocProcessor {
@@ -96,4 +96,30 @@
}
}
+ @Override
+ public void processClassDocWithDocEnv(TypeElement classDoc,
+ ClassDocType classDocType,
+ DocletEnvironment docEnv) {
+ for (DocProcessor docProcessor : _docProcessors) {
+ docProcessor.processClassDocWithDocEnv(classDoc, classDocType, docEnv);
+ }
+ }
+
+ @Override
+ public void processMethodDocWithDocEnv(ExecutableElement methodDoc,
+ MethodDocType methodDocType,
+ DocletEnvironment docEnv) {
+ for (DocProcessor docProcessor : _docProcessors) {
+ docProcessor.processMethodDocWithDocEnv(methodDoc, methodDocType, docEnv);
+ }
+ }
+
+ @Override
+ public void processParamTagWithDocEnv(VariableElement parameter,
+ ParamDocType paramDocType,
+ DocletEnvironment docEnv) {
+ for (DocProcessor docProcessor : _docProcessors) {
+ docProcessor.processParamTagWithDocEnv(parameter, paramDocType, docEnv);
+ }
+ }
}
diff --git a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/ResourceDoclet.java b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/ResourceDoclet.java
index ff94b75..763fb8d 100644
--- a/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/ResourceDoclet.java
+++ b/ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/ResourceDoclet.java
@@ -157,7 +157,7 @@
ClassDocType classDocType = new ClassDocType();
classDocType.setClassName(element.getQualifiedName().toString());
classDocType.setCommentText(getComments(docCommentTree));
- docProcessor.processClassDoc(element, classDocType);
+ docProcessor.processClassDocWithDocEnv(element, classDocType, docEnv);
for (ExecutableElement method : ElementFilter.methodsIn(element.getEnclosedElements())) {
Map<DocTree.Kind, Map<String, String>> tags = getTags(docTrees.getDocCommentTree(method));
MethodTree methodTree = docTrees.getTree(method);
@@ -174,7 +174,7 @@
arguments.append(parameter.asType()).append(COMA);
if (paramDocType != null) {
methodDocType.getParamDocs().add(paramDocType);
- docProcessor.processParamTag(parameter, paramDocType);
+ docProcessor.processParamTagWithDocEnv(parameter, paramDocType, docEnv);
}
}
// Remove last comma if there are parameters
@@ -183,7 +183,7 @@
}
arguments.append(")");
methodDocType.setMethodSignature(arguments.toString());
- docProcessor.processMethodDoc(method, methodDocType);
+ docProcessor.processMethodDocWithDocEnv(method, methodDocType, docEnv);
methodDocType.setRequestDoc(buildRequestDocType(tags));
methodDocType.setResponseDoc(buildResponseDocType(tags));
classDocType.getMethodDocs().add(methodDocType);
