From 62adcb4d142986e30bb9d57cf49be1e4ff2869b1 Mon Sep 17 00:00:00 2001
From: Stephen Webb <swebb2066@gmail.com>
Date: Wed, 24 Jul 2024 09:57:35 +1000
Subject: [PATCH] Document ThreadSpecificData methods

---
 src/main/cpp/threadspecificdata.cpp           | 10 ------
 .../log4cxx/helpers/threadspecificdata.h      | 31 ++++++++++++++++---
 2 files changed, 27 insertions(+), 14 deletions(-)

diff --git a/src/main/cpp/threadspecificdata.cpp b/src/main/cpp/threadspecificdata.cpp
index a0fe34114..ecd70b70c 100644
--- a/src/main/cpp/threadspecificdata.cpp
+++ b/src/main/cpp/threadspecificdata.cpp
@@ -154,16 +154,6 @@ MDC::Map& ThreadSpecificData::getMap()
 	return m_priv->mdcMap;
 }
 
-LogString& ThreadSpecificData::getThreadIdString()
-{
-	return getCurrentData()->m_priv->pNamePair->idString;
-}
-
-LogString& ThreadSpecificData::getThreadName()
-{
-	return getCurrentData()->m_priv->pNamePair->threadName;
-}
-
 auto ThreadSpecificData::getNames() -> NamePairPtr
 {
 	return getCurrentData()->m_priv->pNamePair;
diff --git a/src/main/include/log4cxx/helpers/threadspecificdata.h b/src/main/include/log4cxx/helpers/threadspecificdata.h
index 14078f125..2b7cf2a4c 100644
--- a/src/main/include/log4cxx/helpers/threadspecificdata.h
+++ b/src/main/include/log4cxx/helpers/threadspecificdata.h
@@ -41,26 +41,49 @@ class LOG4CXX_EXPORT ThreadSpecificData
 		 *  @return a pointer that is never null.
 		 */
 		static ThreadSpecificData* getCurrentData();
+
 		/**
-		 *  Release this ThreadSpecficData if empty.
+		 *  Remove current thread data from APR if the diagnostic context is empty.
 		 */
 		void recycle();
 
+		/**
+		 *  Add the \c key \c val pair to the mapped diagnostic context of the current thread
+		 */
 		static void put(const LogString& key, const LogString& val);
+
+		/**
+		 *  Add \c val to the nested diagnostic context of the current thread
+		 */
 		static void push(const LogString& val);
+
+		/**
+		 *  Use \c stack as the nested diagnostic context of the current thread
+		 */
 		static void inherit(const NDC::Stack& stack);
 
+		/**
+		 *  The nested diagnostic context of the current thread
+		 */
 		NDC::Stack& getStack();
+
+		/**
+		 *  The mapped diagnostic context of the current thread
+		 */
 		MDC::Map& getMap();
 
+		/**
+		 *  A character outpur stream only assessable to the current thread
+		 */
 		template <typename T>
 		static std::basic_ostringstream<T>& getStringStream()
 		{
 			return getStream(T());
 		}
-		static LogString& getThreadIdString();
-		static LogString& getThreadName();
 
+		/**
+		 *  The names assigned to the current thread
+		 */
 		struct NamePair
 		{
 			LogString idString;
@@ -68,7 +91,7 @@ class LOG4CXX_EXPORT ThreadSpecificData
 		};
 		using NamePairPtr = std::shared_ptr<NamePair>;
 		/**
-		 *  A reference counted pointer to thread specific strings.
+		 *  A reference counted pointer to the names of the current thread.
 		 *
 		 *  String references will remain valid
 		 *  for the lifetime of this pointer (i.e. even after thread termination).