Claus Ibsen created CAMEL-26666:
-----------------------------------
Summary: Tooling - option descriptions taken from javadoc lose
{@code} text and the characters ? and *
Key: CAMEL-26666
URL: https://issues.apache.org/jira/browse/CAMEL-26666
Project: Camel
Issue Type: Bug
Components: tooling, camel-package-maven-plugin
Reporter: Claus Ibsen
Fix For: 4.24.0
The descriptions that the build tooling takes from javadoc (component, endpoint
and header options, camel-main options) lose part of their text, so the catalog
JSON, the generated docs and the endpoint DSL show garbled descriptions.
*Cause* ({{JavadocHelper.sanitizeDescription}}, camel-tooling-util, main
3f0ea5674020):
* {{\{@code ...\}}} is only unwrapped when the content looks like an identifier
({{\{@\w+\s#?([\w.#(\d,)]+)\}}}). With other content (an {{=}}, a space, a
{{*}}) the tag stays, and the character filter then drops the {{@}}.
* The character filter keeps only Java identifier characters plus
{{.,-='/\!&%():;#$\{\}}}, so {{?}}, {{*}}, {{+}}, {{[}}, {{]}} and {{|}} are
removed from the text.
*Examples*
* camel-main {{camel.server.mcpTags}} ({{HttpServerConfigurationProperties}}
lines 390 and 724): the javadoc {{({@code foo*}), and {@code *} to match all
tags}} becomes {{( \{code foo\} ), and \{code \} to match all tags}} in
{{main.adoc}} and {{camel-main-configuration-metadata.json}}.
* kafka: {{\{code allowManualCommit=true\}}}, {{\{code transacted=true\}}};
exec: {{Whether \{code CamelExec\} in-headers ...}}.
* A named parameter such as {{:?name}} comes out as {{:name}}.
Today the catalog has 52 occurrences of {{\{code }} in 12 files (cxf, exec,
kafka, milo-browse, milo-client, nats, netty, netty-http, opa, openfga, spiffe,
camel-main), plus {{main.adoc}}. Authors work around it by writing plain text.
*Proposal*
* unwrap {{\{@code ...\}}} and {{\{@literal ...\}}} with any content (no nested
braces) before the character filter;
* keep {{?}}, {{*}}, {{+}}, {{[}}, {{]}} and {{|}} in the text;
* a unit test for {{JavadocHelper}} with the examples above;
* regenerate and commit the affected generated files (catalog, docs,
endpoint/component DSL).
* Check {{PrepareCamelJBangCommandsMojo.sanitizeDescription}} for the same
problem.
_Claude Code on behalf of Claus Ibsen (davsclaus)_
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)
