Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhancement for docprocessor #5028

Merged
merged 4 commits into from
Apr 25, 2022
Merged

Enhancement for docprocessor #5028

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
db84692
added docletenvironment as a parameter to DocProcessor functions
Apr 4, 2022
6ede63b
updated copyright
Apr 4, 2022
35760e0
deprecated old process methods, added new process methods with doclet…
Apr 11, 2022
71872ba
updated javadoc
Apr 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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;
Expand Down Expand Up @@ -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);

/**
Expand All @@ -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);

/**
Expand All @@ -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);
}

}
30 changes: 28 additions & 2 deletions ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/DocProcessorWrapper.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 {
Expand Down Expand Up @@ -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);
}
}
}
8 changes: 4 additions & 4 deletions ext/wadl-doclet/src/main/java12/org/glassfish/jersey/wadl/doclet/ResourceDoclet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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);
Expand All @@ -172,7 +172,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
Expand All @@ -181,7 +181,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);
Expand Down