[camel] 01/03: Polish and cleanup documentation

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git

commit 98250f71699216b26c05ef16df6c5774bec14b4e
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Wed Aug 11 14:06:19 2021 +0200

    Polish and cleanup documentation
---
 .../modules/ROOT/pages/oncompletion.adoc           | 76 +++++++++-------------
 1 file changed, 30 insertions(+), 46 deletions(-)

diff --git a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
index 3eb8523..13f140e 100644
--- a/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
+++ b/docs/user-manual/modules/ROOT/pages/oncompletion.adoc
@@ -1,27 +1,25 @@
 [[OnCompletion-OnCompletion]]
 = OnCompletion
 
-Camel has this concept of a Unit of Work that encompass the
+Camel has this concept of a _Unit of Work_ that encompass the
 Exchange. The unit of work among others supports
 synchronization callbacks that are invoked when the
 Exchange is complete. The callback API is defined in
-`org.apache.camel.spi.Synchronization`. and the extended synchronization
+`org.apache.camel.spi.Synchronization` and the extended synchronization
 `org.apache.camel.spi.SynchronizationRouteAware` that have callbacks for
 route events.
 
-*Getting the UnitOfWork*
+== UnitOfWork API
 
 You can get hold of the `org.apache.camel.spi.UnitOfWork` from
 `org.apache.camel.Exchange` with the method `getUnitOfWork()`.
 
-*OnCompletion DSL*
+== OnCompletion DSL
 
-The *onCompletion* EIP supports the following features:
+The OnCompletion EIP supports the following features:
 
-* scope: global and/or per route (route scope override all global scope)
-* multiple global scope
-* triggered either always, only if completed with success, or only if
-failed
+* level: context or route (route level override global level)
+* triggered either always, only if completed with success, or only if failed
 * `onWhen` predicate to only trigger if matched
 * `mode` to define whether to run either before or after
 route consumer writes response back to callee (if its InOut) (default AfterConsumer)
@@ -35,22 +33,21 @@ allows to modify the exchange before the consumer writes back any
 response to the callee. You can use this to for example add customer
 headers, or send to a log to log the response message, etc.
 
-[[OnCompletion-onCompletionwithroutescope]]
-== onCompletion with route scope
+=== onCompletion with route scope
 
-The *onCompletion* DSL allows you to add custom routes/processors when
+The OnCompletion EIP allows you to add custom routes/processors when
 the original Exchange is complete. Camel spins off a
 copy of the Exchange and routes it in a separate
 thread, similar to a Wire Tap. This allows the
-original thread to continue while the *onCompletion* route is running
+original thread to continue while the onCompletion route is running
 concurrently. We chose this model as we did not want the
-*onCompletion* route to interfere with the original route.
+onCompletion route to interfere with the original route.
 
-*Multiple onCompletions allowed at both route and global scope*
+=== Multiple onCompletions
 
-You may define multiple onCompletions at both context and route scope.
-When you define route scoped
-onCompletions then any context scoped are disabled for that given route.
+You may define multiple onCompletions at both context and route level.
+
+When you define route level onCompletions then any context levels are disabled for that given route.
 
 [source,java]
 -----------------------------------------------------------
@@ -67,7 +64,7 @@ from("direct:start")
     .to("mock:result");
 -----------------------------------------------------------
 
-By default the *onCompletion* will be triggered when the
+By default the OnCompletion EIP will be triggered when the
 Exchange is complete and regardless if the
 Exchange completed with success or with a failure
 (such as an Exception was thrown). You can limit the trigger to only
@@ -92,11 +89,9 @@ from("direct:start")
 -----------------------------------------------------------
 
 You can identify if the Exchange is an
-*onCompletion* Exchange as Camel will add the
-property `Exchange.ON_COMPLETION` with a boolean value of `true` when it
-spin-off the *onCompletion* Exchange.
+OnCompletion Exchange as Camel will add the
+property `Exchange.ON_COMPLETION` with a boolean value of `true`.
 
-[[OnCompletion-UsingonCompletionfromSpringDSL]]
 === Using onCompletion from XML DSL
 
 The onCompletion is defined like this with XML DSL:
@@ -118,7 +113,7 @@ The onCompletion is defined like this with XML DSL:
 ----
 
 And the `onCompleteOnly` and `onFailureOnly` is defined as a boolean
-attribute on the <onCompletion> tag so the failure example would be:
+attribute on the `<onCompletion>` tag, so the failure example would be:
 
 [source,xml]
 ----
@@ -135,10 +130,9 @@ attribute on the <onCompletion> tag so the failure example would be:
 </route>
 ----
 
-[[OnCompletion-onCompletionwithglobalscope]]
-== onCompletion with global scope
+=== onCompletion with global level
 
-This works just like the route scope except from the fact that they are
+This works just like the route level except from the fact that they are
 defined globally. An example below:
 
 [source,java]
@@ -151,11 +145,7 @@ from("direct:start")
     .to("mock:result");
 ----
 
-[[OnCompletion-UsingonCompletionfromSpringDSL.1]]
-=== Using onCompletion from Spring DSL
-
-This works just like the route scope except from the fact that they are
-defined globally. An example below:
+And in XML:
 
 [source,xml]
 ----
@@ -173,19 +163,16 @@ defined globally. An example below:
 </route>
 ----
 
-
-*Route scope override Global scope*
-If an *onCompletion* is defined in a route, it overrides *all* global
+IMPORTANT: If an OnCompletion is defined in a route, it overrides *all* global
 scoped and thus it is only the route scoped that are used. The globally
 scoped are not in use.
 
-[[OnCompletion-UsingonCompletionwithonWhenpredicate]]
-== Using onCompletion with onWhen predicate
+=== Using onCompletion with onWhen predicate
 
 As other DSL in Camel you can attach a predicate to
-the *onCompletion* so it only triggers in certain conditions, when the
+the OnCompletion so it only triggers in certain conditions, when the
 predicate matches. For example to only trigger if the message body contains the word
-`Hello` we can do like:
+_Hello_ we can do like:
 
 [source,java]
 ----
@@ -202,7 +189,6 @@ from("direct:start")
     .to("mock:result");
 ----
 
-[[OnCompletion-UsingonCompletionwithorwithoutthreadpool]]
 == Using onCompletion with or without thread pool
 
 To use thread pool then either set a `executorService` or set
@@ -218,7 +204,7 @@ onCompletion().parallelProcessing()
     .setBody(simple("OnComplete:${body}"));
 ----
 
-And in XML DSL
+And in XML DSL:
 
 [source,xml]
 ----
@@ -230,7 +216,7 @@ And in XML DSL
 ----
 
 You can also refer to a specific thread pool
-to be used, using the executorServiceRef option
+to be used, using the `executorServiceRef` option
 
 [source,xml]
 ----
@@ -241,11 +227,9 @@ to be used, using the executorServiceRef option
 </onCompletion>
 ----
 
+=== OnCompletion consumer modes
 
-[[OnCompletion-UsingonCompletiontorunbeforerouteconsumersendsbackresponsetocallee]]
-== Using onCompletion to run before route consumer sends back response to callee
-
-OnCompletion supports two modes
+OnCompletion supports two modes that affects the route consumer:
 
 * AfterConsumer - Default mode which runs after the consumer is done
 * BeforeConsumer - Runs before the consumer is done, and before the