Add safety section to all public unsafe functions

freertos-rust/src/mutex.rs

@@ -126,6 +126,8 @@ where
 
     /// # Safety
     ///
+    /// `handle` must be a valid FreeRTOS mutex handle.
+    ///
     /// The type of `handle` (normal or recursive mutex) must match the type
     /// of instance being created ([`MutexNormal`] or [`MutexRecursive`] respectively).
     unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self;

freertos-rust/src/queue.rs

@@ -31,6 +31,11 @@ impl<T: Sized + Copy> Queue<T> {
         })
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS regular queue handle (not semaphore or mutex).
+    ///
+    /// The item size of the queue must match the size of `T`.
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosQueueHandle) -> Self {
         Self {

freertos-rust/src/semaphore.rs

@@ -34,6 +34,12 @@ impl Semaphore {
         }
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS semaphore handle.
+    ///
+    /// Only binary or counting semaphore is expected here.
+    /// To create mutex from raw handle use [`crate::mutex::MutexInnerImpl::from_raw_handle`].
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosSemaphoreHandle) -> Self {
         Self { semaphore: handle }

freertos-rust/src/task.rs

@@ -105,6 +105,9 @@ impl Task {
         }
     }
 
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS task handle.
     #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosTaskHandle) -> Self {
         Self { task_handle: handle }

freertos-rust/src/timers.rs

@@ -70,6 +70,11 @@ impl Timer {
     }
 
     /// Create a timer from a raw handle.
+    ///
+    /// # Safety
+    ///
+    /// `handle` must be a valid FreeRTOS timer handle.
+    #[inline]
     pub unsafe fn from_raw_handle(handle: FreeRtosTimerHandle) -> Self {
         Self { handle }
     }

freertos-rust/src/utils.rs

@@ -50,6 +50,9 @@ pub fn shim_sanity_check() -> Result<(), TypeSizeError> {
     Ok(())
 }
 
+/// # Safety
+///
+/// `str` must be a pointer to the beginning of nul-terminated sequence of bytes.
 #[cfg(any(feature = "time", feature = "hooks", feature = "sync"))]
 pub unsafe fn str_from_c_string(str: *const u8) -> Result<String, FreeRtosError> {
     let mut buf = Vec::new();