[jira] [Closed] (CAMEL-23789) Improve component docs code examples to be multi-DSL friendly (XML/YAML tabs)

["Claus Ibsen (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/CAMEL-23789?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Claus Ibsen closed CAMEL-23789.
-------------------------------
    Resolution: Fixed

> Improve component docs code examples to be multi-DSL friendly (XML/YAML tabs)
> -----------------------------------------------------------------------------
>
>                 Key: CAMEL-23789
>                 URL: https://issues.apache.org/jira/browse/CAMEL-23789
>             Project: Camel
>          Issue Type: Improvement
>          Components: documentation
>            Reporter: Claus Ibsen
>            Assignee: Claus Ibsen
>            Priority: Major
>             Fix For: 4.21.0
>
>
> While adding XML and YAML DSL tabs to component documentation (PR #24081 added ~480 route examples across ~190 files), a large number of Java DSL code snippets could NOT be translated to XML/YAML because they rely on Java-specific constructs.
> This is a tracking issue to improve these code examples so they are multi-DSL friendly, making documentation more accessible for XML and YAML route authors, and easier for AI agents to translate.
> h3. Patterns that block XML/YAML translation
> The following Java-specific patterns in code examples prevent translation to XML/YAML DSL tabs:
> * *Java lambdas and anonymous Processor classes* — {{.process(exchange -> \{...\})}} and {{new Processor() \{...\}}} are used extensively. Many of these could be replaced with simple {{bean}} calls or {{setHeader}}/{{setBody}} with {{simple}} expressions.
> * *Java constants for header names* — {{SomeConstants.HEADER_NAME}} instead of the actual string value. The docs could show the resolved string values directly (e.g. {{CamelAwsS3Key}} instead of {{S3Constants.KEY}}).
> * *Java constants for operations/enums* — {{SomeEnum.VALUE}}, {{TranslateLanguageEnum.ITALIAN}}, {{VoiceId.JOANNA}}. Could use string values instead.
> * *String concatenation for URIs* — {{"uri" + variable}} breaks the ability to show the URI in XML/YAML. Could use property placeholders instead.
> * *{{.toF()}} / {{.fromF()}} format strings* — Java-only DSL methods. Could be replaced with property placeholders.
> * *Java DataFormat/class variable references* — {{unmarshal(myVar)}}, {{.avro(JsonNode.class)}}, {{.json(JsonLibrary.Jackson)}}. Could use the DSL name directly.
> * *{{template.sendBody()}} / {{consumerTemplate.receiveBody()}}* test API calls — Not routes, but shown as usage examples. Could add equivalent route-based examples.
> * *{{@BindToRegistry}} / {{@Bean}} / {{@Configuration}}* — Spring/CDI annotations for registry setup. Could add XML/YAML bean registration equivalents.
> * *{{RouteBuilder}} class definitions wrapping routes* — The route itself is tabbable, but it's buried inside a class definition. Could extract just the route.
> * *Complex EIP chains* — {{.split(body()).streaming()}}, {{.loopDoWhile()}}, {{.idempotentConsumer()}} with Java method arguments. Some of these have XML/YAML equivalents but are non-trivial.
> * *Bean references via FQN class names* — XML and YAML can reference beans by fully qualified class name (e.g. {{<to uri="bean:com.foo.MyBean"/>}}), but many AI tools and contributors don't know this pattern well, so examples using {{.bean(MyClass.class)}} aren't being translated.
> h3. Suggested improvements
> # *Replace Java constants with string values in examples* — Show the actual header/operation name string so XML/YAML users can use it directly. Keep a note that Java users can use the constant.
> # *Replace lambdas with bean references where possible* — Use {{.bean("myProcessor")}} or {{.to("bean:myProcessor")}} instead of inline lambdas, with the bean class shown separately.
> # *Use property placeholders instead of string concatenation* — Replace {{"uri" + port}} with {{"uri?port=\{\{myPort\}\}"}}.
> # *Extract routes from RouteBuilder class definitions* — Show just the route DSL, not the surrounding Java class boilerplate.
> # *Add bean FQN examples* — Show that XML/YAML can call beans via {{bean:com.foo.MyClass}} without requiring registry setup.
> # *Make examples more low-code friendly* — Prefer {{simple}} expressions, {{setHeader}}/{{setBody}} with constants, and declarative patterns over imperative Java code.
> h3. Files with the most untranslated examples
> ||Component||Untranslated count||
> |camel-pqc|64|
> |camel-langchain4j-agent|50|
> |camel-bindy|49|
> |camel-mina-sftp|48|
> |camel-azure-storage-blob|35|
> |camel-aws2-s3|32|
> |camel-ibm-watsonx-ai|31|
> |camel-openai|30|
> |camel-spring-ai-chat|29|
> |camel-aws-bedrock|29|
> |camel-kafka|27|
> |camel-mongodb|26|
> |camel-salesforce|23|
> |camel-mock|22|
> |camel-dapr|21|
> |camel-jms|20|
> Related PR: https://github.com/apache/camel/pull/24081



--
This message was sent by Atlassian Jira
(v8.20.10#820010)