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