From ce201ea248154c44f9615c3661d630b08fd86f3d Mon Sep 17 00:00:00 2001
From: Ceki Gulcu <ceki@qos.ch>
Date: Thu, 7 Dec 2023 13:37:59 +0100
Subject: [PATCH] more tests, more javadocs

Signed-off-by: Ceki Gulcu <ceki@qos.ch>
---
 .../src/main/java/org/slf4j/MDCHelper.java    | 26 +++++++++++
 .../test/java/org/slf4j/MDCHelperTest.java    | 45 ++++++++++++++++++-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/slf4j-api/src/main/java/org/slf4j/MDCHelper.java b/slf4j-api/src/main/java/org/slf4j/MDCHelper.java
index 41e12f49f..3797da972 100644
--- a/slf4j-api/src/main/java/org/slf4j/MDCHelper.java
+++ b/slf4j-api/src/main/java/org/slf4j/MDCHelper.java
@@ -32,6 +32,32 @@
 /**
  * This class assists in the creation and removal (aka closing) of MDC entries.
  *
+ * <p>Typical Usage example:</p>
+ *
+ * <pre>
+ *  MDCHelper mdch = new MDCHelper();
+ *  try {
+ *    mdch.put("k0", "v0");
+ *    throw new RuntimeException();
+ *  } catch (RuntimeException e) {
+ *    // here MDC.get("k0") would return "v0"
+ *  } finally {
+ *    // MDC remove "k0"
+ *    mdch.removeSet();
+ *  }
+ * </pre>
+ *
+ * <p>It is also possible to chain {@link #put} invocations. For example:</p>
+ * <pre>
+ *   MDCHelper mdch = new MDCHelper();
+ *   try {
+ *     // assume "k0" was added to MDC at an earlier stage
+ *     mdch.addKey("k0").put("k1", "v1").put("k2, "v2");
+ *   } finally {
+ *     // MDC remove "k0", "k1", "k2"
+ *     mdch.removeSet();
+ *   }
+ * </pre>
  * @since 2.0.10
  */
 public class MDCHelper  {
diff --git a/slf4j-api/src/test/java/org/slf4j/MDCHelperTest.java b/slf4j-api/src/test/java/org/slf4j/MDCHelperTest.java
index 2d14b13f1..944df1574 100644
--- a/slf4j-api/src/test/java/org/slf4j/MDCHelperTest.java
+++ b/slf4j-api/src/test/java/org/slf4j/MDCHelperTest.java
@@ -29,7 +29,6 @@
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNull;
-import static org.junit.Assert.assertTrue;
 
 public class MDCHelperTest {
 
@@ -39,6 +38,10 @@ public class MDCHelperTest {
 
     String k0 = "k0";
     String v0 = "v0";
+    String k1 = "k1";
+    String v1 = "v0";
+    String k2 = "k2";
+    String v2 = "v2";
     String kUnused = "kUnused";
 
     void throwRuntimeException() {
@@ -69,4 +72,44 @@ public void empty() {
         }
         assertNull(mdcAdapter.get(k0));
     }
+
+    @Test
+    public void addKeyTest() {
+        mdcAdapter.put(k0, v0);
+        try {
+            mdch.addKey(k0);
+            assertEquals(v0, mdcAdapter.get(k0));
+            assertNull(mdcAdapter.get(kUnused));
+            throwRuntimeException();
+        } catch (RuntimeException e) {
+            assertEquals(v0, mdcAdapter.get(k0));
+        } finally {
+            mdch.removeSet();
+        }
+        assertNull(mdcAdapter.get(k0));
+    }
+
+    @Test
+    public void combinedPut_addKeyTest() {
+        mdcAdapter.put(k0, v0);
+        try {
+            mdch.addKey(k0).put(k1, v1).put(k2, v2);
+            assertEquals(v0, mdcAdapter.get(k0));
+            assertEquals(v1, mdcAdapter.get(k1));
+            assertEquals(v2, mdcAdapter.get(k2));
+            assertNull(mdcAdapter.get(kUnused));
+            throwRuntimeException();
+        } catch (RuntimeException e) {
+            assertEquals(v0, mdcAdapter.get(k0));
+            assertEquals(v1, mdcAdapter.get(k1));
+            assertEquals(v2, mdcAdapter.get(k2));
+        } finally {
+            mdch.removeSet();
+        }
+        assertNull(mdcAdapter.get(k0));
+        assertNull(mdcAdapter.get(k1));
+        assertNull(mdcAdapter.get(k2));
+    }
+
+
 }