Enhancement for docprocessor (#5028)

Co-authored-by: jm041977 <[email protected]>
eclipse-ee4j · Apr 25, 2022 · 08bfa50 · 08bfa50
1 parent 01b88fe
commit 08bfa50
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 6 deletions.
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
@@ -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 @@ public interface DocProcessor {
      * @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 @@ public interface DocProcessor {
      * @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 @@ public interface DocProcessor {
      * @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
@@ -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 @@ public void processParamTag(VariableElement parameter,
         }
     }
 
+    @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
@@ -157,7 +157,7 @@ public boolean run(DocletEnvironment docEnv) {
                     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 @@ public boolean run(DocletEnvironment docEnv) {
                             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 @@ public boolean run(DocletEnvironment docEnv) {
                         }
                         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);