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 <[email protected]> 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; }
