docs: Add warning about using std::counting_semaphore (#5595)

This adds a comment to avoid using `std::counting_semaphore` until the minimum compiler versions of GCC and Clang have been updated to no longer contain the bug that is present in older compilers.

Author: vlntb

src/xrpld/core/detail/semaphore.h

@@ -17,6 +17,34 @@
 */
 //==============================================================================
 
+/**
+ *
+ * TODO: Remove ripple::basic_semaphore (and this file) and use
+ * std::counting_semaphore.
+ *
+ * Background:
+ * - PR: https://github.com/XRPLF/rippled/pull/5512/files
+ * - std::counting_semaphore had a bug fixed in both GCC and Clang:
+ *     * GCC PR 104928: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=104928
+ *     * LLVM PR 79265: https://github.com/llvm/llvm-project/pull/79265
+ *
+ * GCC:
+ * According to GCC Bugzilla PR104928
+ * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=104928#c15), the fix is
+ * scheduled for inclusion in GCC 16.0 (see comment #15, Target
+ * Milestone: 16.0). It is not included in GCC 14.x or earlier, and there is no
+ * indication that it will be backported to GCC 13.x or 14.x branches.
+ *
+ * Clang:
+ * The fix for is included in Clang 19.1.0+
+ *
+ * Once the minimum compiler version is updated to > GCC 16.0 or Clang 19.1.0,
+ * we can remove this file.
+ *
+ * WARNING: Avoid using std::counting_semaphore until the minimum compiler
+ * version is updated.
+ */
+
 #ifndef RIPPLE_CORE_SEMAPHORE_H_INCLUDED
 #define RIPPLE_CORE_SEMAPHORE_H_INCLUDED