From ec172d482191ddd46e64a2c93febd4ef95f27ebd Mon Sep 17 00:00:00 2001
From: Dom Dwyer <dom@itsallbroken.com>
Date: Wed, 31 Aug 2022 10:35:48 +0200
Subject: [PATCH] docs: document panics / track_caller

Document merging permits from distinct Semaphore instances causes a
panic, and add #[track_caller] annotation.
---
 tokio/src/sync/semaphore.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/tokio/src/sync/semaphore.rs b/tokio/src/sync/semaphore.rs
index 317f8c39b8a..ccf44ba8a88 100644
--- a/tokio/src/sync/semaphore.rs
+++ b/tokio/src/sync/semaphore.rs
@@ -625,6 +625,12 @@ impl<'a> SemaphorePermit<'a> {
     /// without releasing the permits it holds.
     ///
     /// Permits held by both `self` and `other` are released when `self` drops.
+    ///
+    /// # Panics
+    ///
+    /// This function panics if permits from different [`Semaphore`] instances
+    /// are merged.
+    #[track_caller]
     pub fn merge(&mut self, mut other: Self) {
         assert!(
             std::ptr::eq(self.sem, other.sem),
@@ -647,6 +653,12 @@ impl OwnedSemaphorePermit {
     /// without releasing the permits it holds.
     ///
     /// Permits held by both `self` and `other` are released when `self` drops.
+    ///
+    /// # Panics
+    ///
+    /// This function panics if permits from different [`Semaphore`] instances
+    /// are merged.
+    #[track_caller]
     pub fn merge(&mut self, mut other: Self) {
         assert!(
             Arc::ptr_eq(&self.sem, &other.sem),