From 7f2cdeefdc7015e7035003777272d9ed4967289e Mon Sep 17 00:00:00 2001
From: Alex Martens <alex@thinglab.org>
Date: Sun, 9 Mar 2025 12:24:33 -0700
Subject: [PATCH] BinaryHeap: fix missing safety doc

---
 src/binary_heap.rs | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/src/binary_heap.rs b/src/binary_heap.rs
index 5125aede..f7239b47 100644
--- a/src/binary_heap.rs
+++ b/src/binary_heap.rs
@@ -386,7 +386,24 @@ where
 
     /// Removes the *top* (greatest if max-heap, smallest if min-heap) item from the binary heap and
     /// returns it, without checking if the binary heap is empty.
-    #[allow(clippy::missing_safety_doc)] // TODO
+    ///
+    /// # Safety
+    ///
+    /// The binary heap must not be empty.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use heapless::binary_heap::{BinaryHeap, Max};
+    ///
+    /// let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
+    /// heap.push(42)?;
+    ///
+    /// // SAFETY: We just pushed a number onto the heap, so it cannot be empty.
+    /// let val = unsafe { heap.pop_unchecked() };
+    /// assert_eq!(val, 42);
+    /// # Ok::<(), u8>(())
+    /// ```
     pub unsafe fn pop_unchecked(&mut self) -> T {
         let mut item = self.data.pop_unchecked();
 
@@ -420,7 +437,23 @@ where
     }
 
     /// Pushes an item onto the binary heap without first checking if it's full.
-    #[allow(clippy::missing_safety_doc)] // TODO
+    ///
+    /// # Safety
+    ///
+    /// The binary heap must not be full.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use heapless::binary_heap::{BinaryHeap, Max};
+    ///
+    /// let mut heap: BinaryHeap<_, Max, 8> = BinaryHeap::new();
+    ///
+    /// // SAFETY: We just created an empty heap of size 8, so it cannot be full.
+    /// unsafe { heap.push_unchecked(42) };
+    /// assert_eq!(heap.len(), 1);
+    /// assert_eq!(heap.peek(), Some(&42));
+    /// ```
     pub unsafe fn push_unchecked(&mut self, item: T) {
         let old_len = self.len();
         self.data.push_unchecked(item);