You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2022/04/01 08:53:36 UTC
[camel] branch CAMEL-17896/use-javadoc-as-default-description created (now 3e4f405)
This is an automated email from the ASF dual-hosted git repository.
nfilotto pushed a change to branch CAMEL-17896/use-javadoc-as-default-description
in repository https://gitbox.apache.org/repos/asf/camel.git.
at 3e4f405 CAMEL-17896: Extract the description of an header from the Javadoc by default
This branch includes the following new commits:
new 3e4f405 CAMEL-17896: Extract the description of an header from the Javadoc by default
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[camel] 01/01: CAMEL-17896: Extract the description of an header from the Javadoc by default
Posted by nf...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
nfilotto pushed a commit to branch CAMEL-17896/use-javadoc-as-default-description
in repository https://gitbox.apache.org/repos/asf/camel.git
commit 3e4f405dd9301fc7fd74bcf4d9de7ccd990458b1
Author: Nicolas Filotto <nf...@talend.com>
AuthorDate: Fri Apr 1 10:40:45 2022 +0200
CAMEL-17896: Extract the description of an header from the Javadoc by default
---
.../packaging/EndpointSchemaGeneratorMojo.java | 68 ++++++++++++++++++----
.../packaging/EndpointSchemaGeneratorMojoTest.java | 31 +++++++++-
.../maven/packaging/endpoint/SomeConstants.java | 5 ++
...a => SomeEndpointWithJavadocAsDescription.java} | 19 +++---
.../packaging/endpoint/SomeEnumConstants.java | 7 ++-
5 files changed, 109 insertions(+), 21 deletions(-)
diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
index 5ae8dbf..fb9c3e3 100644
--- a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
+++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojo.java
@@ -84,8 +84,11 @@ import org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.ASTNode;
import org.jboss.forge.roaster._shade.org.eclipse.jdt.core.dom.Javadoc;
import org.jboss.forge.roaster.model.JavaDoc;
import org.jboss.forge.roaster.model.JavaDocCapable;
+import org.jboss.forge.roaster.model.source.FieldHolderSource;
import org.jboss.forge.roaster.model.source.FieldSource;
import org.jboss.forge.roaster.model.source.JavaClassSource;
+import org.jboss.forge.roaster.model.source.JavaEnumSource;
+import org.jboss.forge.roaster.model.source.JavaSource;
import org.jboss.forge.roaster.model.source.MethodSource;
import org.jboss.jandex.AnnotationInstance;
import org.jboss.jandex.AnnotationTarget;
@@ -118,7 +121,7 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
protected Map<String, String> resources = new HashMap<>();
protected List<Path> sourceRoots;
protected Map<String, String> sources = new HashMap<>();
- protected Map<String, JavaClassSource> parsed = new HashMap<>();
+ protected Map<String, JavaSource<?>> parsed = new HashMap<>();
@Override
public void execute() throws MojoExecutionException, MojoFailureException {
@@ -363,7 +366,11 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
return false;
}
final EndpointHeaderModel header = new EndpointHeaderModel();
- header.setDescription(metadata.description().trim());
+ String description = metadata.description().trim();
+ if (description.isEmpty()) {
+ description = getHeaderFieldJavadoc(field);
+ }
+ header.setDescription(description);
header.setKind("header");
header.setDisplayName(metadata.displayName());
header.setJavaType(metadata.javaType());
@@ -393,6 +400,42 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
return true;
}
+ /**
+ * @param headerField the field for which we want to extract the related Javadoc.
+ * @return the Javadoc of the header field if any. An empty string otherwise.
+ */
+ private String getHeaderFieldJavadoc(Field headerField) {
+ JavaSource<?> source;
+ final String className = headerField.getDeclaringClass().getName();
+ try {
+ source = javaSource(className, JavaSource.class);
+ if (source == null) {
+ getLog().debug(String.format("The source of the class %s could not be found", className));
+ return "";
+ }
+ } catch (Exception e) {
+ getLog().debug(
+ String.format("An error occurred while loading the source of the class %s could not be found", className),
+ e);
+ return "";
+ }
+ JavaDocCapable<?> member = null;
+ if (source instanceof JavaEnumSource) {
+ member = ((JavaEnumSource) source).getEnumConstant(headerField.getName());
+ } else if (source instanceof FieldHolderSource) {
+ member = ((FieldHolderSource<?>) source).getField(headerField.getName());
+ } else {
+ getLog().debug(String.format("The header field cannot be retrieved from a source of type %s", source.getName()));
+ }
+ if (member != null) {
+ String doc = getJavaDocText(loadJavaSource(className), member);
+ if (!Strings.isNullOrEmpty(doc)) {
+ return doc;
+ }
+ }
+ return "";
+ }
+
private String getExcludedEnd(Metadata classElement) {
String excludedEndpointProperties = "";
if (classElement != null) {
@@ -444,10 +487,11 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
return data;
}
- private void enhanceComponentModel(
+ void enhanceComponentModel(
ComponentModel componentModel, ComponentModel parentData, String excludedEndpointProperties,
String excludedComponentProperties) {
componentModel.getComponentOptions().removeIf(option -> filterOutOption(componentModel, option));
+ componentModel.getEndpointHeaders().forEach(option -> fixDoc(option, null));
componentModel.getComponentOptions()
.forEach(option -> fixDoc(option, parentData != null ? parentData.getComponentOptions() : null));
componentModel.getComponentOptions().sort(EndpointHelper.createGroupAndLabelComparator());
@@ -455,7 +499,7 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
componentModel.getEndpointOptions()
.forEach(option -> fixDoc(option, parentData != null ? parentData.getEndpointOptions() : null));
componentModel.getEndpointOptions().sort(EndpointHelper.createOverallComparator(componentModel.getSyntax()));
- // merge with parent, removing excluded and overriden properties
+ // merge with parent, remove excluded and override properties
if (parentData != null) {
Set<String> componentOptionNames
= componentModel.getComponentOptions().stream().map(BaseOptionModel::getName).collect(Collectors.toSet());
@@ -1505,7 +1549,7 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
JavaClassSource source;
try {
- source = javaClassSource(classElement.getName());
+ source = javaSource(classElement.getName(), JavaClassSource.class);
if (source == null) {
return "";
}
@@ -1595,12 +1639,12 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
}
private String getDocComment(Class<?> classElement) {
- JavaClassSource source = javaClassSource(classElement.getName());
+ JavaClassSource source = javaSource(classElement.getName(), JavaClassSource.class);
return getJavaDocText(loadJavaSource(classElement.getName()), source);
}
- private JavaClassSource javaClassSource(String className) {
- return parsed.computeIfAbsent(className, this::doParseJavaClassSource);
+ private <T extends JavaSource<?>> T javaSource(String className, Class<T> targetType) {
+ return targetType.cast(parsed.computeIfAbsent(className, this::doParseJavaSource));
}
private List<Path> getSourceRoots() {
@@ -1612,13 +1656,13 @@ public class EndpointSchemaGeneratorMojo extends AbstractGeneratorMojo {
return sourceRoots;
}
- private JavaClassSource doParseJavaClassSource(String className) {
+ private JavaSource<?> doParseJavaSource(String className) {
try {
String source = loadJavaSource(className);
- if (source != null) {
- return (JavaClassSource) Roaster.parse(source);
- } else {
+ if (source == null) {
return null;
+ } else {
+ return (JavaSource<?>) Roaster.parse(source);
}
} catch (Exception e) {
throw new RuntimeException("Unable to parse java class " + className, e);
diff --git a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojoTest.java b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojoTest.java
index 9032107..903fad2 100644
--- a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojoTest.java
+++ b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/EndpointSchemaGeneratorMojoTest.java
@@ -23,6 +23,7 @@ import org.apache.camel.maven.packaging.endpoint.SomeEndpoint;
import org.apache.camel.maven.packaging.endpoint.SomeEndpointUsingEnumConstants;
import org.apache.camel.maven.packaging.endpoint.SomeEndpointWithBadHeaders;
import org.apache.camel.maven.packaging.endpoint.SomeEndpointWithFilter;
+import org.apache.camel.maven.packaging.endpoint.SomeEndpointWithJavadocAsDescription;
import org.apache.camel.maven.packaging.endpoint.SomeEndpointWithoutHeaders;
import org.apache.camel.spi.UriEndpoint;
import org.apache.camel.tooling.model.ComponentModel;
@@ -60,7 +61,7 @@ class EndpointSchemaGeneratorMojoTest {
void testCanRetrieveMetadataOfHeaders(Class<?> clazz) {
mojo.addEndpointHeaders(model, clazz.getAnnotation(UriEndpoint.class), "some");
List<EndpointHeaderModel> endpointHeaders = model.getEndpointHeaders();
- assertEquals(2, endpointHeaders.size());
+ assertEquals(3, endpointHeaders.size());
// Full
EndpointHeaderModel headerFull = endpointHeaders.get(0);
assertEquals("header", headerFull.getKind());
@@ -92,6 +93,22 @@ class EndpointSchemaGeneratorMojoTest {
assertTrue(headerEmpty.getLabel().isEmpty());
assertNull(headerEmpty.getEnums());
assertEquals("common", headerEmpty.getGroup());
+ // Empty with Javadoc as description
+ EndpointHeaderModel headerEmptyWithJavadoc = endpointHeaders.get(2);
+ assertEquals("header", headerEmptyWithJavadoc.getKind());
+ assertEquals("KEY_EMPTY_WITH_JAVA_DOC", headerEmptyWithJavadoc.getName());
+ assertEquals("Some description", headerEmptyWithJavadoc.getDescription());
+ assertTrue(headerEmptyWithJavadoc.getDisplayName().isEmpty());
+ assertTrue(headerEmptyWithJavadoc.getJavaType().isEmpty());
+ assertFalse(headerEmptyWithJavadoc.isRequired());
+ assertInstanceOf(String.class, headerEmptyWithJavadoc.getDefaultValue());
+ assertTrue(((String) headerEmptyWithJavadoc.getDefaultValue()).isEmpty());
+ assertFalse(headerEmptyWithJavadoc.isDeprecated());
+ assertTrue(headerEmptyWithJavadoc.getDeprecationNote().isEmpty());
+ assertFalse(headerEmptyWithJavadoc.isSecret());
+ assertTrue(headerEmptyWithJavadoc.getLabel().isEmpty());
+ assertNull(headerEmptyWithJavadoc.getEnums());
+ assertEquals("common", headerEmptyWithJavadoc.getGroup());
}
@Test
@@ -117,4 +134,16 @@ class EndpointSchemaGeneratorMojoTest {
assertEquals(String.format("keep-%d", i + 1), headerEmpty.getName());
}
}
+
+ @Test
+ void testEndpointWithCleanedJavadocAsDescription() {
+ mojo.addEndpointHeaders(model, SomeEndpointWithJavadocAsDescription.class.getAnnotation(UriEndpoint.class), "some");
+ mojo.enhanceComponentModel(model, null, "", "");
+ List<EndpointHeaderModel> endpointHeaders = model.getEndpointHeaders();
+ assertEquals(1, endpointHeaders.size());
+ EndpointHeaderModel headerEmpty = endpointHeaders.get(0);
+ assertEquals("header", headerEmpty.getKind());
+ assertEquals("no-description", headerEmpty.getName());
+ assertEquals("Some description about NO_DESCRIPTION.", headerEmpty.getDescription());
+ }
}
diff --git a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeConstants.java b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeConstants.java
index f58468d..407bec9 100644
--- a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeConstants.java
+++ b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeConstants.java
@@ -26,6 +26,11 @@ public final class SomeConstants {
public static final String KEY_FULL = "KEY_FULL";
@Metadata
static final String KEY_EMPTY = "KEY_EMPTY";
+ /**
+ * Some description
+ */
+ @Metadata
+ static final String KEY_EMPTY_WITH_JAVA_DOC = "KEY_EMPTY_WITH_JAVA_DOC";
private SomeConstants() {
}
diff --git a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEndpointWithJavadocAsDescription.java
similarity index 68%
copy from tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java
copy to tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEndpointWithJavadocAsDescription.java
index e00be68..24ed6ba 100644
--- a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java
+++ b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEndpointWithJavadocAsDescription.java
@@ -17,13 +17,18 @@
package org.apache.camel.maven.packaging.endpoint;
import org.apache.camel.spi.Metadata;
+import org.apache.camel.spi.UriEndpoint;
-public enum SomeEnumConstants {
- @Deprecated
- @Metadata(description = "key full desc", label = "my label", displayName = "my display name",
- javaType = "org.apache.camel.maven.packaging.endpoint.SomeEndpoint$MyEnum", required = true,
- defaultValue = "VAL1", deprecationNote = "my deprecated note", secret = true)
- KEY_FULL,
+@UriEndpoint(scheme = "some", syntax = "some", title = "some", headersClass = SomeEndpointWithJavadocAsDescription.class)
+public final class SomeEndpointWithJavadocAsDescription {
+
+ /**
+ * Some description about {@link #NO_DESCRIPTION}.
+ */
@Metadata
- KEY_EMPTY;
+ static final String NO_DESCRIPTION = "no-description";
+
+ private SomeEndpointWithJavadocAsDescription() {
+
+ }
}
diff --git a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java
index e00be68..969ef13 100644
--- a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java
+++ b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/endpoint/SomeEnumConstants.java
@@ -25,5 +25,10 @@ public enum SomeEnumConstants {
defaultValue = "VAL1", deprecationNote = "my deprecated note", secret = true)
KEY_FULL,
@Metadata
- KEY_EMPTY;
+ KEY_EMPTY,
+ /**
+ * Some description
+ */
+ @Metadata
+ KEY_EMPTY_WITH_JAVA_DOC;
}