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 aad01013513d53bd2e5971162828480da4dff5b3 Author: Lars Heinemann <[email protected]> AuthorDate: Fri Nov 6 09:05:39 2026 +0100 CAMEL-26666: Preserve Javadoc option descriptions Unwrap code and literal tags, retain option syntax, and escape comment terminators when rendering generated Java DSL documentation. Cover the sanitizer, DSL renderers, and metadata generation with regression tests. Co-authored-by: OpenAI Codex <[email protected]> --- .../apache/camel/tooling/util/JavadocHelper.java | 5 ++- .../camel/tooling/util/JavadocHelperTest.java | 34 +++++++++++++++++ .../apache/camel/component/foo/FooEndpoint.java | 2 +- .../src/it/HeaderSupport/verify.groovy | 5 ++- .../camel/maven/packaging/ComponentDslMojo.java | 2 +- .../camel/maven/packaging/EndpointDslMojo.java | 2 +- .../camel/maven/packaging/dsl/DslHelper.java | 4 ++ .../camel/maven/packaging/DslJavadocTest.java | 43 ++++++++++++++++++++++ 8 files changed, 92 insertions(+), 5 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 319bba36dfa1..8fbf5338427f 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 @@ -20,7 +20,7 @@ import static org.apache.camel.tooling.util.Strings.isNullOrEmpty; public final class JavadocHelper { - private static final String VALID_CHARS = ".,-='/\\!&%():;#${}"; + private static final String VALID_CHARS = ".,-='/\\!&%():;#${}?*+[]|"; private JavadocHelper() { } @@ -96,6 +96,9 @@ public final class JavadocHelper { s = s.replaceAll("@\\{link\\s\\w+\\s(\\w+)}", "$1"); s = s.replaceAll("@\\{link\\s([\\w]+)}", "$1"); + // Code and literal tags can contain spaces and punctuation, not just Java identifiers. + s = s.replaceAll("\\{@(?:code|literal)\\s+([^{}]*)}", "$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/camel-tooling-util/src/test/java/org/apache/camel/tooling/util/JavadocHelperTest.java b/tooling/camel-tooling-util/src/test/java/org/apache/camel/tooling/util/JavadocHelperTest.java index 6e1698f78b98..bf4fe65d5649 100644 --- a/tooling/camel-tooling-util/src/test/java/org/apache/camel/tooling/util/JavadocHelperTest.java +++ b/tooling/camel-tooling-util/src/test/java/org/apache/camel/tooling/util/JavadocHelperTest.java @@ -18,6 +18,9 @@ package org.apache.camel.tooling.util; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.junit.jupiter.params.provider.ValueSource; public class JavadocHelperTest { @@ -70,6 +73,37 @@ public class JavadocHelperTest { + " to wait a little period to ensure no further message arrives. This is what you can use this setAssertPeriod(long) method for. By default" + " this period is disabled."; + @ParameterizedTest + @CsvSource(delimiter = '|', value = { + "Use {@code allowManualCommit=true}.|Use allowManualCommit=true.", + "Use {@literal transacted=true}.|Use transacted=true.", + "Matches ({@code foo*}), and {@code *} to match all tags.|Matches (foo*), and * to match all tags.", + "Use {@literal foo bar} or {@code foo bar}.|Use foo bar or foo bar.", + "Use {@code #name} and {@literal #name}.|Use #name and #name.", + "Use {@code $1} and {@literal $2}.|Use $1 and $2.", + "Use {@code } then {@literal }.|Use then ." + }) + void testSanitizeInlineCodeAndLiteral(String javadoc, String expected) { + Assertions.assertEquals(expected, JavadocHelper.sanitizeDescription(javadoc, false)); + } + + @ParameterizedTest + @ValueSource(booleans = { false, true }) + void testPreserveOptionSyntax(boolean summary) { + String javadoc = "Use :?name, foo*, [a-z]+ and foo|bar."; + Assertions.assertEquals(javadoc, JavadocHelper.sanitizeDescription(javadoc, summary)); + Assertions.assertEquals(javadoc, JavadocHelper.sanitizeDescription( + "Use {@literal :?name}, {@literal foo*}, {@code [a-z]+} and {@code foo|bar}.", summary)); + } + + @Test + void testSanitizeMultilineCode() { + String javadoc = " * Use {@code foo\n * bar*} and {@literal :?name}.\n * More details."; + Assertions.assertEquals("Use foo bar* and :?name. More details.", + JavadocHelper.sanitizeDescription(javadoc, false)); + Assertions.assertEquals("Use foo bar* and :?name.", JavadocHelper.sanitizeDescription(javadoc, true)); + } + @Test public void testSanitizeJavaDoc() throws Exception { String s = "* more memory. The total size is provided in the {@link org.apache.camel.Exchange#SPLIT_SIZE} header."; diff --git a/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/src/main/java/org/apache/camel/component/foo/FooEndpoint.java b/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/src/main/java/org/apache/camel/component/foo/FooEndpoint.java index 11c178a03a01..d598ccba0932 100644 --- a/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/src/main/java/org/apache/camel/component/foo/FooEndpoint.java +++ b/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/src/main/java/org/apache/camel/component/foo/FooEndpoint.java @@ -40,7 +40,7 @@ public class FooEndpoint { } /** - * My interval in seconds. + * My interval in seconds. Use {@code intervalSeconds=5} to poll every five seconds. */ public void setIntervalSeconds(int intervalSeconds) { this.intervalSeconds = intervalSeconds; diff --git a/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/verify.groovy b/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/verify.groovy index a1ce29b9152f..a04c88d9d3e1 100644 --- a/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/verify.groovy +++ b/tooling/maven/camel-package-maven-plugin/src/it/HeaderSupport/verify.groovy @@ -18,9 +18,12 @@ import org.apache.camel.tooling.model.ComponentModel import org.apache.camel.tooling.model.JsonMapper -File json = new File(basedir, "src/generated/resources/org/apache/camel/component/foo/foo.json") +File json = new File(basedir, "src/generated/resources/META-INF/org/apache/camel/component/foo/foo.json") assert json.exists() ComponentModel component = JsonMapper.generateComponentModel(json.text) assert component.getEndpointHeaders().size() == 1 assert "My description of the SomeHeader".equals(component.getEndpointHeaders().get(0).getDescription()) + +assert "My interval in seconds. Use intervalSeconds=5 to poll every five seconds.".equals( + component.getEndpointOptions().find { it.getName() == "intervalSeconds" }.getDescription()) diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ComponentDslMojo.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ComponentDslMojo.java index c34084be927c..731e76985ce5 100644 --- a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ComponentDslMojo.java +++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/ComponentDslMojo.java @@ -232,7 +232,7 @@ public class ComponentDslMojo extends AbstractGeneratorMojo { StringBuilder sb = new StringBuilder(doc.length() * 2); sb.append("/**\n"); int len = 78 - indent.length(); - String rem = xmlEncode(doc); + String rem = DslHelper.escapeJavadocCommentEnd(xmlEncode(doc)); while (!rem.isEmpty()) { int idx = rem.length() >= len ? rem.substring(0, len).lastIndexOf(' ') : -1; int idx2 = rem.indexOf('\n'); 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 b9adc9b036a2..b657329f6332 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 @@ -450,7 +450,7 @@ public class EndpointDslMojo extends AbstractGeneratorMojo { public String javadoc(String indent, String doc) { StringBuilder sb = new StringBuilder(doc.length() * 2); - List<String> lines = formatJavadocOrCommentStringAsList(doc, indent); + List<String> lines = formatJavadocOrCommentStringAsList(DslHelper.escapeJavadocCommentEnd(doc), indent); if (!lines.isEmpty()) { sb.append("/**\n"); for (String line : lines) { diff --git a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/dsl/DslHelper.java b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/dsl/DslHelper.java index 42e9d0abe8e3..56752bdf79c0 100644 --- a/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/dsl/DslHelper.java +++ b/tooling/maven/camel-package-maven-plugin/src/main/java/org/apache/camel/maven/packaging/dsl/DslHelper.java @@ -23,6 +23,10 @@ public final class DslHelper { private DslHelper() { } + public static String escapeJavadocCommentEnd(String text) { + return text.replace("*/", "*/"); + } + public static String toCamelCaseLower(final String schema) { String convertedText = CaseUtils.toCamelCase(schema, false, '-', '+'); if (convertedText != null) { diff --git a/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/DslJavadocTest.java b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/DslJavadocTest.java new file mode 100644 index 000000000000..04edefd8ef04 --- /dev/null +++ b/tooling/maven/camel-package-maven-plugin/src/test/java/org/apache/camel/maven/packaging/DslJavadocTest.java @@ -0,0 +1,43 @@ +/* + * 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; + +import org.apache.camel.tooling.util.JavadocHelper; +import org.junit.jupiter.api.Test; + +import static org.assertj.core.api.Assertions.assertThat; + +class DslJavadocTest { + + private static final String DESCRIPTION = "Matches {@code *}/{@code *} media types."; + + @Test + void testEndpointJavadocEscapesCommentEnd() { + String description = JavadocHelper.sanitizeDescription(DESCRIPTION, false); + assertThat(description).isEqualTo("Matches */* media types."); + assertThat(new EndpointDslMojo(null, null).javadoc("", description)) + .isEqualTo("/**\n * Matches */* media types.\n */"); + } + + @Test + void testComponentJavadocEscapesCommentEnd() { + String description = JavadocHelper.sanitizeDescription(DESCRIPTION, false); + assertThat(description).isEqualTo("Matches */* media types."); + assertThat(new ComponentDslMojo(null, null).javadoc("", description)) + .isEqualTo("/**\n * Matches */* media types.\n */"); + } +}
