zephyr: various comment cleanups from review suggestions

Fix some typos and clarify safety in a few places.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/src/kio.rs

@@ -42,8 +42,15 @@ where
 /// Arrange to have the given future run on the current worker thread.  The resulting `JoinHandle`
 /// has `join` and `join_async` methods that can be used to wait for the given thread.
 ///
-/// The main use for this is to allow work threads to use `Rc` and `Rc<RefCell<T>>` within async
-/// tasks.  The main constraint is that references inside cannot be held across an `.await`.
+/// By constraining the spawn to the current worker, this function is able to remove the Send
+/// constraint from the future (and its return type), allowing tasks to share data using
+/// lighter-weight mechanimsms, such as `Rc` and `Rc<RefCell<T>>`, or `&'static RefCell<T>`.
+///
+/// To be able to use tasks running on different workers, sharing must be done with types such as
+/// `Arc`, and `Arc<Mutex<T>>`, or `&'static Mutex<T>`.
+///
+/// It is important, when using RefCell, that a borrow from the cell not be carried across an await
+/// boundary, or RefCell's runtime multi-borrow check can cause a panic.
 ///
 /// # Panics
 /// If this is called other than from a worker task running on a work thread, it will panic.
@@ -56,7 +63,7 @@ where
 }
 
 /// Yield the current thread, returning it to the work queue to be run after other work on that
-/// queue.  (This has to be called `yield_now` in Rust, because `yield` is a keyword.
+/// queue.  (This has to be called `yield_now` in Rust, because `yield` is a keyword.)
 pub fn yield_now() -> impl Future<Output = ()> {
     YieldNow { waited: false }
 }

zephyr/src/kio/sync.rs

@@ -56,7 +56,6 @@ pub struct MutexGuard<'a, T: ?Sized + 'a> {
     _nosend: PhantomData<UnsafeCell<()>>,
 }
 
-// unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
 unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
 
 impl<T> Mutex<T> {

zephyr/src/work.rs

@@ -133,7 +133,7 @@
 //!   WORKER_STACK: ThreadStack<2048>;
 //! }
 //! // ...
-//! let main_worker = Box::new(j
+//! let main_worker = Box::new(
 //!     WorkQueueBuilder::new()
 //!         .set_priority(2).
 //!         .set_name(c"mainloop")
@@ -309,7 +309,7 @@ impl WorkQueueBuilder {
 /// // Leak a work queue in a Box.
 /// let wq = Box::new(WorkQueueBuilder::new().start(...));
 /// let _ = Box::leak(wq);
-///
+/// ```
 pub struct WorkQueue {
     #[allow(dead_code)]
     item: Fixed<k_work_q>,
@@ -335,7 +335,7 @@ impl Drop for WorkQueue {
 /// The work queue is protected with a sync Mutex (which uses an underlying Zephyr mutex).  It is,
 /// in general, not a good idea to use a mutex in a work queue, as deadlock can happen.  So it is
 /// important to both never .await while holding the lock, as well as to make sure operations within
-/// it are relatively fast.  In this case, `jnsert` and `get` on the SimpleTls are reasonably fast.
+/// it are relatively fast.  In this case, `insert` and `get` on the SimpleTls are reasonably fast.
 /// `insert` is usually done just at startup as well.
 ///
 /// This is a little bit messy as we don't have a lazy mechanism, so we have to handle this a bit