You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by da...@apache.org on 2020/09/15 15:56:54 UTC
[camel] 05/22: CAMEL-15478: api-component should generate @ApiParam
with more fine grained details so we know which parameter is for which api
method.
This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch api
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 4835563d36dab943ad961e537ac94883912ee31c
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Sat Sep 12 11:33:25 2020 +0200
CAMEL-15478: api-component should generate @ApiParam with more fine grained details so we know which parameter is for which api method.
---
.../apache/camel/tooling/util/JavadocHelper.java | 6 ++-
.../maven/AbstractApiMethodGeneratorMojo.java | 1 -
.../maven/JavaSourceApiMethodGeneratorMojo.java | 1 +
.../org/apache/camel/maven/JavaSourceParser.java | 43 +++++++++++++++++++---
.../org/apache/camel/maven/SignatureModel.java | 9 +++++
.../apache/camel/maven/JavaSourceParserTest.java | 10 +++++
6 files changed, 62 insertions(+), 8 deletions(-)
diff --git a/tooling/camel-tooling-util/src/main/java/org/apache/camel/tooling/util/JavadocHelper.java b/tooling/camel-tooling-util/src/main/java/org/apache/camel/tooling/util/JavadocHelper.java
index 2d821eb..de0ac0c 100644
--- a/tooling/camel-tooling-util/src/main/java/org/apache/camel/tooling/util/JavadocHelper.java
+++ b/tooling/camel-tooling-util/src/main/java/org/apache/camel/tooling/util/JavadocHelper.java
@@ -89,9 +89,13 @@ public final class JavadocHelper {
String s = sb.toString();
// remove all XML tags
s = s.replaceAll("<.*?>", "");
- // remove @link inlined javadoc links which is special handled
+ // remove {@link inlined javadoc links which is special handled
s = s.replaceAll("\\{@link\\s\\w+\\s(\\w+)}", "$1");
s = s.replaceAll("\\{@link\\s([\\w]+)}", "$1");
+ // also remove the commonly mistake to do with @{link
+ s = s.replaceAll("@\\{link\\s\\w+\\s(\\w+)}", "$1");
+ s = s.replaceAll("@\\{link\\s([\\w]+)}", "$1");
+
// remove all inlined javadoc links, eg such as {@link org.apache.camel.spi.Registry}
// use #? to remove leading # in case its a local reference
s = s.replaceAll("\\{@\\w+\\s#?([\\w.#(\\d,)]+)}", "$1");
diff --git a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/AbstractApiMethodGeneratorMojo.java b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/AbstractApiMethodGeneratorMojo.java
index 8e2fa7e..e77b99b 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/AbstractApiMethodGeneratorMojo.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/AbstractApiMethodGeneratorMojo.java
@@ -390,7 +390,6 @@ public abstract class AbstractApiMethodGeneratorMojo extends AbstractApiMethodBa
sb.append("{");
for (int i = 0; i < methods.size(); i++) {
String method = methods.get(i);
- // TODO: Add description and signature
sb.append("@ApiMethod(methodName = \"").append(method).append("\")");
if (i < methods.size() - 1) {
sb.append(", ");
diff --git a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceApiMethodGeneratorMojo.java b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceApiMethodGeneratorMojo.java
index 742c460..f5d3319 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceApiMethodGeneratorMojo.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceApiMethodGeneratorMojo.java
@@ -114,6 +114,7 @@ public class JavaSourceApiMethodGeneratorMojo extends AbstractApiMethodGenerator
SignatureModel model = new SignatureModel();
model.setApiDescription(parser.getApiDescription());
model.setSignature(method);
+ model.setMethodDescription(parser.getMethodDescriptions().get(name));
Map<String, String> params = parser.getParameters().get(name);
model.setParameters(params);
result.put(method, model);
diff --git a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
index 935e41f..ac1e466 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/JavaSourceParser.java
@@ -46,6 +46,7 @@ public class JavaSourceParser {
private Map<String, Map<String, String>> parameters = new LinkedHashMap<>();
private String errorMessage;
private String apiDescription;
+ private final Map<String, String> methodDescriptions = new HashMap<>();
public synchronized void parse(InputStream in, String innerClass) throws Exception {
JavaClassSource rootClazz = (JavaClassSource) Roaster.parse(in);
@@ -60,10 +61,12 @@ public class JavaSourceParser {
}
}
- String doc = getClassJavadocRaw(clazz);
+ String rawClass = clazz.toUnformattedString();
+ String doc = getClassJavadocRaw(clazz, rawClass);
apiDescription = sanitizeJavaDocValue(doc, true);
if (apiDescription == null || apiDescription.isEmpty()) {
- doc = getClassJavadocRaw(rootClazz);
+ rawClass = rootClazz.toUnformattedString();
+ doc = getClassJavadocRaw(rootClazz, rawClass);
apiDescription = sanitizeJavaDocValue(doc, true);
}
if (apiDescription != null && apiDescription.indexOf('.') > 0) {
@@ -75,6 +78,16 @@ public class JavaSourceParser {
if (!ms.isPublic() || ms.isConstructor()) {
continue;
}
+
+ doc = getMethodJavadocRaw(ms, rawClass);
+ doc = sanitizeJavaDocValue(doc, true);
+ if (doc != null && doc.indexOf('.') > 0) {
+ doc = StringHelper.before(doc, ".");
+ }
+ if (doc != null && !doc.isEmpty()) {
+ methodDescriptions.put(ms.getName(), doc);
+ }
+
String signature = ms.toSignature();
// roaster signatures has return values at end
// public create(String, AddressRequest) : Result
@@ -240,15 +253,29 @@ public class JavaSourceParser {
* Gets the class javadoc raw (incl line breaks and tags etc). The roaster API returns the javadoc with line breaks
* and others removed
*/
- private static String getClassJavadocRaw(JavaClassSource clazz) {
+ private static String getClassJavadocRaw(JavaClassSource clazz, String rawClass) {
Object obj = clazz.getJavaDoc().getInternal();
ASTNode node = (ASTNode) obj;
int pos = node.getStartPosition();
int len = node.getLength();
if (pos > 0 && len > 0) {
- String txt = clazz.toUnformattedString();
- String doc = txt.substring(pos, pos + len);
- return doc;
+ return rawClass.substring(pos, pos + len);
+ } else {
+ return null;
+ }
+ }
+
+ /**
+ * Gets the method javadoc raw (incl line breaks and tags etc). The roaster API returns the javadoc with line breaks
+ * and others removed
+ */
+ private static String getMethodJavadocRaw(MethodSource ms, String rawClass) {
+ Object obj = ms.getJavaDoc().getInternal();
+ ASTNode node = (ASTNode) obj;
+ int pos = node.getStartPosition();
+ int len = node.getLength();
+ if (pos > 0 && len > 0) {
+ return rawClass.substring(pos, pos + len);
} else {
return null;
}
@@ -298,6 +325,7 @@ public class JavaSourceParser {
methods.clear();
methodText.clear();
parameters.clear();
+ methodDescriptions.clear();
errorMessage = null;
apiDescription = null;
}
@@ -322,4 +350,7 @@ public class JavaSourceParser {
return apiDescription;
}
+ public Map<String, String> getMethodDescriptions() {
+ return methodDescriptions;
+ }
}
diff --git a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/SignatureModel.java b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/SignatureModel.java
index 419cc14..cfa1f50 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/SignatureModel.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/main/java/org/apache/camel/maven/SignatureModel.java
@@ -25,6 +25,7 @@ public class SignatureModel {
private String apiName;
private String apiDescription;
+ private String methodDescription;
private String signature;
private Map<String, String> parameters;
@@ -44,6 +45,14 @@ public class SignatureModel {
this.apiDescription = apiDescription;
}
+ public String getMethodDescription() {
+ return methodDescription;
+ }
+
+ public void setMethodDescription(String methodDescription) {
+ this.methodDescription = methodDescription;
+ }
+
public String getSignature() {
return signature;
}
diff --git a/tooling/maven/camel-api-component-maven-plugin/src/test/java/org/apache/camel/maven/JavaSourceParserTest.java b/tooling/maven/camel-api-component-maven-plugin/src/test/java/org/apache/camel/maven/JavaSourceParserTest.java
index 63e16fa..b7eb376 100644
--- a/tooling/maven/camel-api-component-maven-plugin/src/test/java/org/apache/camel/maven/JavaSourceParserTest.java
+++ b/tooling/maven/camel-api-component-maven-plugin/src/test/java/org/apache/camel/maven/JavaSourceParserTest.java
@@ -124,4 +124,14 @@ public class JavaSourceParserTest {
assertEquals("Provides methods to create, delete, find, and update Customer objects", desc);
}
+ @Test
+ public void testMethodJavadoc() throws Exception {
+ final JavaSourceParser parser = new JavaSourceParser();
+
+ parser.parse(JavaSourceParserTest.class.getResourceAsStream("/DisputeGateway.java"), null);
+
+ String desc = parser.getMethodDescriptions().get("addFileEvidence");
+ assertEquals("Add File Evidence to a Dispute, given an ID and a FileEvidenceRequest File evidence request", desc);
+ }
+
}