Merge pull request #536 from newAM/binary-heap-safety

BinaryHeap: fix missing safety doc

Author: reitermarkus

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);