CAMEL-23535: camel-api - enhance class-level javadoc for lifecycle and context types

[ammachado]

Description

CAMEL-23535 asks for an audit and enhancement of the javadoc in core/camel-api so that classes better explain what they are, what they do, and how they fit into the framework, with links to the relevant user-manual pages.

This PR is the first batch of that work: class-level javadoc on the lifecycle and context family of top-level public-API types. Scope is intentionally narrow so the prose style can be reviewed before the rest of core/camel-api is updated.

Changes

Class-level javadoc expanded on 18 top-level types in org.apache.camel:

• Context: CamelContext, CamelContextAware, CamelContextLifecycle, CatalogCamelContext, ExtendedCamelContext, ContextEvents
• Service lifecycle: Service, ServiceStatus, StatefulService
• Exceptions: RuntimeCamelException, CamelException, CamelExchangeException, AlreadyStoppedException, FailedToCreateRouteException, FailedToStartRouteException, FailedToStartComponentException, FailedToCreateConsumerException, FailedToCreateProducerException

Each updated docblock follows the same pattern: a one-sentence what-it-is, a paragraph on the role in routing / lifecycle, sibling-type {@link} references, and (where a matching user-manual page exists) one <a href="https://camel.apache.org/manual/..."> link. The convention matches the existing javadoc style in Endpoint.java, Component.java, Processor.java, Message.java, Route.java.

The change is comment-only: no signatures, behaviour, or runtime code is altered.

Out of scope (follow-ups)

• Public-method javadoc gap-filling in core/camel-api.
• The rest of the top-level org.apache.camel.* surface (messaging core, endpoints/components/producers/consumers, routes & builders, annotations & functional types) will land as subsequent batches under the same JIRA.
• org.apache.camel.spi.* and other sub-packages (catalog, console, cloudevents, cluster, clock, ai, health, vault, resume, trait, support).

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change.

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.
• I have run `mvn clean install -DskipTests` locally from root folder and I have committed all auto-generated changes.

---

Claude Code on behalf of Adriano Machado

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• core/camel-api
• docs

ℹ️ Dependent modules were not tested because the total number of affected modules exceeded the threshold (50). Use the test-dependents label to force testing all dependents.

Build reactor — dependencies compiled but only changed modules were tested (2 modules)

• Camel :: API
• Camel :: Docs

---

⚙️ View full build and test results