You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by or...@apache.org on 2022/04/25 17:07:25 UTC
[camel] 02/03: CAMEL-17894: move some of the JavaDoc code to their own utility class
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 9f6417e5fb55a690dd639c0251aa5a43011f22dc
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Mon Apr 25 17:36:31 2022 +0200
CAMEL-17894: move some of the JavaDoc code to their own utility class
---
.../camel/maven/packaging/EndpointDslMojo.java | 97 ++---------------
.../maven/packaging/generics/JavadocUtil.java | 116 +++++++++++++++++++++
2 files changed, 127 insertions(+), 86 deletions(-)
diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointDslMojo.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointDslMojo.java
index c4d1c6a3276..fbe6a7347ef 100644
--- a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointDslMojo.java
+++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointDslMojo.java
@@ -20,8 +20,6 @@ import java.io.File;
import java.io.FileFilter;
import java.io.IOException;
import java.io.InputStream;
-import java.io.LineNumberReader;
-import java.io.StringReader;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Arrays;
@@ -34,6 +32,7 @@ import java.util.stream.Collectors;
import javax.annotation.Generated;
import org.apache.camel.maven.packaging.dsl.DslHelper;
+import org.apache.camel.maven.packaging.generics.JavadocUtil;
import org.apache.camel.tooling.model.BaseModel;
import org.apache.camel.tooling.model.ComponentModel;
import org.apache.camel.tooling.model.ComponentModel.EndpointOptionModel;
@@ -52,13 +51,14 @@ import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.project.MavenProject;
import org.apache.maven.project.MavenProjectHelper;
import org.jboss.forge.roaster.Roaster;
-import org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.ASTNode;
import org.jboss.forge.roaster.model.Type;
import org.jboss.forge.roaster.model.source.JavaClassSource;
import org.jboss.forge.roaster.model.source.MethodSource;
import org.jboss.forge.roaster.model.source.ParameterSource;
import org.sonatype.plexus.build.incremental.BuildContext;
+import static org.apache.camel.maven.packaging.generics.JavadocUtil.getMainDescription;
+import static org.apache.camel.maven.packaging.generics.JavadocUtil.pathParameterJavaDoc;
import static org.apache.camel.maven.packaging.generics.PackagePluginUtils.joinHeaderAndSource;
import static org.apache.camel.tooling.util.PackageHelper.findCamelDirectory;
import static org.apache.camel.tooling.util.PackageHelper.loadText;
@@ -379,12 +379,14 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
boolean firstAlias = true;
for (ComponentModel componentModel : aliases) {
- String desc = getMainDescription(componentModel);
- String methodName = camelCaseLower(componentModel.getScheme());
+ final String desc = getMainDescription(componentModel);
+ final String methodName = camelCaseLower(componentModel.getScheme());
Method method = doAddMethod(javaClass, builderClass, dslClass, componentModel, methodName);
String javaDoc = desc;
+
javaDoc += "\n\n@param path " + pathParameterJavaDoc(componentModel);
javaDoc += "\n@return the dsl builder\n";
+
method.getJavaDoc().setText(javaDoc);
if (componentModel.isDeprecated()) {
method.addAnnotation(Deprecated.class);
@@ -409,6 +411,7 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
.setReturnType(new GenericType(loadClass(builderClass.getCanonicalName())))
.setDefault()
.setBodyF("return %s.%s(%s);", javaClass.getName(), "endpointBuilder", "componentName, path");
+
javaDoc = desc;
javaDoc += "\n\n@param componentName to use a custom component name for the endpoint instead of the default name";
javaDoc += "\n@param path " + pathParameterJavaDoc(componentModel);
@@ -728,15 +731,6 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
return answer;
}
- private static String pathParameterJavaDoc(ComponentModel model) {
- int pos = model.getSyntax().indexOf(':');
- if (pos != -1) {
- return model.getSyntax().substring(pos + 1);
- } else {
- return model.getSyntax();
- }
- }
-
private boolean synchronizeEndpointBuilderFactoryInterface(List<File> factories) throws MojoFailureException {
JavaClass javaClass = new JavaClass(getProjectClassLoader());
javaClass.setPackage(endpointFactoriesPackageName);
@@ -828,7 +822,7 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
method.addParameter(getQualifiedType(ps.getType()), ps.getName());
}
}
- String doc = extractJavaDoc(sourceCode, ms);
+ String doc = JavadocUtil.extractJavaDoc(sourceCode, ms);
method.getJavaDoc().setFullText(doc);
if (ms.getAnnotation(Deprecated.class) != null) {
method.addAnnotation(Deprecated.class);
@@ -871,34 +865,9 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
return val;
}
+ @Deprecated
protected static String extractJavaDoc(String sourceCode, MethodSource ms) throws IOException {
- // the javadoc is mangled by roaster (sadly it does not preserve newlines and original formatting)
- // so we need to load it from the original source file
- Object internal = ms.getJavaDoc().getInternal();
- if (internal instanceof ASTNode) {
- int pos = ((ASTNode) internal).getStartPosition();
- int len = ((ASTNode) internal).getLength();
- if (pos > 0 && len > 0) {
- String doc = sourceCode.substring(pos, pos + len);
- LineNumberReader ln = new LineNumberReader(new StringReader(doc));
- String line;
- StringBuilder sb = new StringBuilder();
- while ((line = ln.readLine()) != null) {
- line = line.trim();
- if (line.startsWith("/**") || line.startsWith("*/")) {
- continue;
- }
- if (line.startsWith("*")) {
- line = line.substring(1).trim();
- }
- sb.append(line);
- sb.append("\n");
- }
- doc = sb.toString();
- return doc;
- }
- }
- return null;
+ return JavadocUtil.extractJavaDoc(sourceCode, ms);
}
private List<File> loadAllComponentsDslEndpointFactoriesAsFile() {
@@ -934,50 +903,6 @@ public class EndpointDslMojo extends AbstractGeneratorMojo {
return s.substring(0, i) + s.substring(i + 1, i + 2).toUpperCase() + s.substring(i + 2);
}
- private static String getMainDescription(ComponentModel model) {
- StringBuilder descSb = new StringBuilder(512);
-
- descSb.append(model.getTitle()).append(" (").append(model.getArtifactId()).append(")");
- descSb.append("\n").append(model.getDescription());
- descSb.append("\n");
- descSb.append("\nCategory: ").append(model.getLabel());
- descSb.append("\nSince: ").append(model.getFirstVersionShort());
- descSb.append("\nMaven coordinates: ").append(model.getGroupId()).append(":").append(model.getArtifactId());
-
- // include javadoc for all path parameters and mark which are required
- descSb.append("\n");
- descSb.append("\nSyntax: <code>").append(model.getSyntax()).append("</code>");
- for (EndpointOptionModel option : model.getEndpointOptions()) {
- if ("path".equals(option.getKind())) {
- descSb.append("\n");
- descSb.append("\nPath parameter: ").append(option.getName());
- if (option.isRequired()) {
- descSb.append(" (required)");
- }
- if (option.isDeprecated()) {
- descSb.append(" <strong>deprecated</strong>");
- }
- descSb.append("\n").append(option.getDescription());
- if (option.getDefaultValue() != null) {
- descSb.append("\nDefault value: ").append(option.getDefaultValue());
- }
- // TODO: default value note ?
- if (option.getEnums() != null && !option.getEnums().isEmpty()) {
- descSb.append("\nThere are ").append(option.getEnums().size())
- .append(" enums and the value can be one of: ")
- .append(wrapEnumValues(option.getEnums()));
- }
- }
- }
-
- return descSb.toString();
- }
-
- private static String wrapEnumValues(List<String> enumValues) {
- // comma to space so we can wrap words (which uses space)
- return String.join(", ", enumValues);
- }
-
private String getComponentNameFromType(String type) {
int pos = type.lastIndexOf('.');
String name = type.substring(pos + 1).replace("Component", "");
diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/generics/JavadocUtil.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/generics/JavadocUtil.java
new file mode 100644
index 00000000000..df855ceab09
--- /dev/null
+++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/generics/JavadocUtil.java
@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.camel.maven.packaging.generics;
+
+import java.io.IOException;
+import java.io.LineNumberReader;
+import java.io.StringReader;
+import java.util.List;
+
+import org.apache.camel.tooling.model.ComponentModel;
+import org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.ASTNode;
+import org.jboss.forge.roaster.model.source.MethodSource;
+
+public final class JavadocUtil {
+ private JavadocUtil() {
+
+ }
+
+ public static String getMainDescription(ComponentModel model) {
+ StringBuilder descSb = new StringBuilder(512);
+
+ descSb.append(model.getTitle()).append(" (").append(model.getArtifactId()).append(")");
+ descSb.append("\n").append(model.getDescription());
+ descSb.append("\n");
+ descSb.append("\nCategory: ").append(model.getLabel());
+ descSb.append("\nSince: ").append(model.getFirstVersionShort());
+ descSb.append("\nMaven coordinates: ").append(model.getGroupId()).append(":").append(model.getArtifactId());
+
+ // include javadoc for all path parameters and mark which are required
+ descSb.append("\n");
+ descSb.append("\nSyntax: <code>").append(model.getSyntax()).append("</code>");
+ for (ComponentModel.EndpointOptionModel option : model.getEndpointOptions()) {
+ if ("path".equals(option.getKind())) {
+ descSb.append("\n");
+ descSb.append("\nPath parameter: ").append(option.getName());
+ if (option.isRequired()) {
+ descSb.append(" (required)");
+ }
+ if (option.isDeprecated()) {
+ descSb.append(" <strong>deprecated</strong>");
+ }
+ descSb.append("\n").append(option.getDescription());
+ if (option.getDefaultValue() != null) {
+ descSb.append("\nDefault value: ").append(option.getDefaultValue());
+ }
+ // TODO: default value note ?
+ if (option.getEnums() != null && !option.getEnums().isEmpty()) {
+ descSb.append("\nThere are ").append(option.getEnums().size())
+ .append(" enums and the value can be one of: ")
+ .append(wrapEnumValues(option.getEnums()));
+ }
+ }
+ }
+
+ return descSb.toString();
+ }
+
+ private static String wrapEnumValues(List<String> enumValues) {
+ // comma to space so we can wrap words (which uses space)
+ return String.join(", ", enumValues);
+ }
+
+ public static String pathParameterJavaDoc(ComponentModel model) {
+ int pos = model.getSyntax().indexOf(':');
+ if (pos != -1) {
+ return model.getSyntax().substring(pos + 1);
+ } else {
+ return model.getSyntax();
+ }
+ }
+
+ public static String extractJavaDoc(String sourceCode, MethodSource ms) throws IOException {
+ // the javadoc is mangled by roaster (sadly it does not preserve newlines and original formatting)
+ // so we need to load it from the original source file
+ Object internal = ms.getJavaDoc().getInternal();
+ if (internal instanceof ASTNode) {
+ int pos = ((ASTNode) internal).getStartPosition();
+ int len = ((ASTNode) internal).getLength();
+ if (pos > 0 && len > 0) {
+ String doc = sourceCode.substring(pos, pos + len);
+ LineNumberReader ln = new LineNumberReader(new StringReader(doc));
+ String line;
+ StringBuilder sb = new StringBuilder();
+ while ((line = ln.readLine()) != null) {
+ line = line.trim();
+ if (line.startsWith("/**") || line.startsWith("*/")) {
+ continue;
+ }
+ if (line.startsWith("*")) {
+ line = line.substring(1).trim();
+ }
+ sb.append(line);
+ sb.append("\n");
+ }
+ doc = sb.toString();
+ return doc;
+ }
+ }
+ return null;
+ }
+}