From a663e522a67304ce57affd8b714bbbfb5fa52ff6 Mon Sep 17 00:00:00 2001
From: Matej Novotny <manovotn@redhat.com>
Date: Mon, 2 Sep 2024 14:23:36 +0200
Subject: [PATCH] Update javadoc of RequestContextController with suggested
 usage

---
 .../control/RequestContextController.java       | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java b/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java
index 1bf0067b..6ca7e2a9 100644
--- a/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java
+++ b/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java
@@ -17,7 +17,7 @@
 import jakarta.enterprise.context.ContextNotActiveException;
 
 /**
- * The CDI container provides a built in instance of RequestContextController that is dependent scoped for the purposes
+ * The CDI container provides a built-in instance of {@code RequestContextController} that is dependent scoped for the purposes
  * of activating and deactivating. For example:
  *
  * <pre>
@@ -26,12 +26,15 @@
  *
  * public void doRequest(String body) {
  *     // activate request context
- *     requestContextController.activate();
- *
- *     // do work in a request context.
- *
- *     // deactivate the request context
- *     requestContextController.deactivate();
+ *     boolean activated = requestContextController.activate();
+ *     try {
+ *         // do work in a request context.
+ *     } finally {
+ *         // deactivate the request context if we activated it earlier
+ *         if (activated) {
+ *             requestContextController.deactivate();
+ *         }
+ *     }
  * }
  * </pre>
  *