update documentation, code comments; and doc symlinks where appropriate

Fixed a bunch of typos, grammar errors, capitalisation issues, etc.
Also promoted some comments to actual documentation where appropriate.
Added links to actual symbols too when it makes sense.

examples/cooperative_preempt.rs

@@ -6,35 +6,39 @@ use std::{
     time::{Duration, Instant},
 };
 
+/// Glommio is a cooperative thread per core system so once you start
+/// processing a future it will run it to completion. This is not great
+/// for latency, and may be outright wrong if you have tasks that may
+/// spin forever before returning, like a long-lived server.
+///
+/// Applications using Glommio are then expected to be well-behaved and
+/// explicitly yield control if they are going to do something that may take
+/// too long (that is usually a loop!)
+///
+/// There are three ways of yielding control:
+///
+///  * [`glommio::executor().yield_if_needed()`], which will yield if the
+///    current task queue has run for too long. What "too long" means is an
+///    implementation detail, but it will be always somehow related to the
+///    latency guarantees that the task queues want to uphold in their
+///    [`Latency::Matters`] parameter (or [`Latency::NotImportant`]). To check
+///    whether preemption is needed without yielding automatically, use
+///    [`glommio::executor().need_preempt()`].
+///
+///  * [`glommio::executor().yield_task_queue_now()`], works like
+///    yield_if_needed() but yields unconditionally.
+///
+///  * [`glommio::executor().yield_now()`], which unconditional yield the
+///    current task within the current task queue, forcing the scheduler to run
+///    another task on the same task queue. This is equivalent to returning
+///    `Poll::Pending` and waking up the current task.
+///
+/// Because [`yield_if_needed()`] returns a future that has to be .awaited,
+/// it cannot be used in situations where .await is illegal. For
+/// instance, if we are holding a borrow. For those, one can call
+/// [`need_preempt()`] which will tell you if yielding is needed, and
+/// then explicitly yield with [`yield_task_queue_now()`].
 fn main() {
-    // Glommio is a cooperative thread per core system so once you start processing
-    // a future it will run it to completion. This is not great for latency, and
-    // may be outright wrong if you have tasks that may spin forever before
-    // returning, like a long-lived server.
-    //
-    // Applications using Glommio are then expected to be well-behaved and
-    // explicitly yield control if they are going to do something that may take
-    // too long (that is usually a loop!)
-    //
-    // There are three ways of yielding control:
-    //
-    //  * glommio::executor().yield_if_needed(), which will yield if the current
-    //    task queue has run for too long. What "too long" means is an
-    //    implementation detail, but it will be always somehow related to the
-    //    latency guarantees that the task queues want to uphold in their
-    //    `Latency::Matters` parameter (or Latency::NotImportant).
-    //
-    //  * glommio::executor().yield_task_queue_now(), works like yield_if_needed()
-    //    but yields unconditionally.
-    //
-    //  * glommio::executor().yield_now(), which unconditional yield the current
-    //    task within the current task queue, forcing the scheduler to run another
-    //    task on the same task queue.
-    //
-    // Because yield_if_needed() returns a future that has to be .awaited, it cannot
-    // be used in situations where .await is illegal. For instance, if we are
-    // holding a borrow. For those, one can call need_preempt() which will tell
-    // you if yielding is needed, and then explicitly yield with later().
     let handle = LocalExecutorBuilder::new()
         .spawn(|| async move {
             let tq1 = glommio::executor().create_task_queue(

examples/echo.rs

@@ -107,7 +107,7 @@ fn main() -> Result<()> {
 
     // Congrats for getting to the end of this example!
     //
-    // Now can you adapt it so it uses multiple executors and all CPUs in your
+    // Now can you adapt it, so it uses multiple executors and all CPUs in your
     // system?
     server_handle.join().unwrap();
     Ok(())

examples/hyper.rs

@@ -1,9 +1,9 @@
-// Example on how to use the Hyper server in !Send mode.
-// The clients are harder, see https://github.com/hyperium/hyper/issues/2341 for details
-//
-// Essentially what we do is we wrap our types around the Tokio traits. The
-// !Send limitation makes it harder to deal with high level hyper primitives but
-// it works in the end.
+/// Example on how to use the Hyper server in !Send mode.
+/// The clients are harder, see https://github.com/hyperium/hyper/issues/2341 for details
+///
+/// Essentially what we do is we wrap our types around the Tokio traits. The
+/// `!Send` limitation makes it harder to deal with high level hyper primitives,
+/// but it works in the end.
 mod hyper_compat {
     use futures_lite::{AsyncRead, AsyncWrite, Future};
     use hyper::service::service_fn;

glommio/src/channels/local_channel.rs

@@ -700,14 +700,14 @@ impl<'a, T> Drop for ChannelStream<'a, T> {
 impl<T> LocalReceiver<T> {
     /// Receives data from this channel
     ///
-    /// If the sender is no longer available it returns [`None`]. Otherwise
+    /// If the sender is no longer available it returns [`None`]. Otherwise,
     /// block until an item is available and returns it wrapped in [`Some`]
     ///
     /// Notice that this is also available as a Stream. Whether to consume from
     /// a stream or `recv` is up to the application. The biggest difference
     /// is that [`StreamExt`]'s [`next`] method takes a mutable reference to
     /// self. If the LocalReceiver is, say, behind an [`Rc`] it may be more
-    /// ergonomic to recv.
+    /// ergonomic to `recv`.
     ///
     /// # Examples
     /// ```

glommio/src/channels/mod.rs

@@ -7,7 +7,7 @@
 //! abstractions.
 
 /// A single-producer, single-consumer lock-free queue, allowing two threads
-/// to efficently communicate.
+/// to efficiently communicate.
 pub mod spsc_queue;
 
 /// Allow data to be transmitted across two tasks in the same shard.

glommio/src/channels/sharding.rs

@@ -22,8 +22,8 @@ pub trait Handler<T>: Clone {
     /// Handle a message either received from an external stream of forwarded
     /// from another peer.
     /// * `msg` - The message to handle.
-    /// * `src_shard` - Id of the shard where the msg is from.
-    /// * `cur_shard` - Id of the local shard.
+    /// * `src_shard` - ID of the shard where the msg is from.
+    /// * `cur_shard` - ID of the local shard.
     fn handle(&self, msg: T, src_shard: usize, cur_shard: usize) -> HandlerResult;
 }
 
@@ -134,7 +134,7 @@ impl<T: Send + 'static, H: Handler<T> + 'static> Sharded<T, H> {
 
     /// Close this [`Sharded`] and wait for all existing background tasks to
     /// finish. No more consuming task will be spawned, but incoming
-    /// messages from the streams consumed by existing back ground tasks
+    /// messages from the streams consumed by existing background tasks
     /// will not be rejected. So it would be important to truncate the streams
     /// from upstream before calling this method to prevent it from hanging.
     pub async fn close(&mut self) {

glommio/src/channels/shared_channel.rs

@@ -25,7 +25,7 @@ use std::{
 type Result<T, V> = crate::Result<T, V>;
 
 /// The `SharedReceiver` is the receiving end of the Shared Channel.
-/// It implements [`Send`] so it can be passed to any thread. However
+/// It implements [`Send`] so it can be passed to any thread. However,
 /// it doesn't implement any method: before it is used it must be changed
 /// into a [`ConnectedReceiver`], which then makes sure it will be used by
 /// at most one thread.
@@ -41,7 +41,7 @@ pub struct SharedReceiver<T: Send + Sized> {
 }
 
 /// The `SharedSender` is the sending end of the Shared Channel.
-/// It implements [`Send`] so it can be passed to any thread. However
+/// It implements [`Send`] so it can be passed to any thread. However,
 /// it doesn't implement any method: before it is used it must be changed
 /// into a [`ConnectedSender`], which then makes sure it will be used by
 /// at most one thread.
@@ -143,7 +143,7 @@ impl<T: BufferHalf + Clone> Future for Connector<T> {
     }
 }
 
-/// Creates a a new `shared_channel` returning its sender and receiver
+/// Creates a new `shared_channel` returning its sender and receiver
 /// endpoints.
 ///
 /// All shared channels must be bounded.
@@ -348,14 +348,14 @@ impl<T: 'static + Send + Sized> SharedReceiver<T> {
 impl<T: Send + Sized> ConnectedReceiver<T> {
     /// Receives data from this channel
     ///
-    /// If the sender is no longer available it returns [`None`]. Otherwise
+    /// If the sender is no longer available it returns [`None`]. Otherwise,
     /// block until an item is available and returns it wrapped in [`Some`]
     ///
     /// Notice that this is also available as a Stream. Whether to consume from
     /// a stream or `recv` is up to the application. The biggest difference
     /// is that [`StreamExt`]'s [`next`] method takes a mutable reference to
     /// self. If the LocalReceiver is, say, behind an [`Rc`] it may be more
-    /// ergonomic to recv.
+    /// ergonomic to `recv`.
     ///
     /// # Examples
     /// ```

glommio/src/channels/spsc_queue.rs

@@ -39,8 +39,8 @@ struct Slot<T> {
 
 /// The internal memory buffer used by the queue.
 ///
-/// Buffer holds a pointer to allocated memory which represents the bounded
-/// ring buffer, as well as a head and tail atomicUsize which the producer and
+/// `Buffer` holds a pointer to allocated memory which represents the bounded
+/// ring buffer, as well as a head and tail `AtomicUsize` which the producer and
 /// consumer use to track location in the ring.
 #[repr(C)]
 pub(crate) struct Buffer<T> {
@@ -129,7 +129,7 @@ impl<T> Buffer<T> {
     /// If the buffer is empty, this method will not block. Instead, it will
     /// return `None` signifying the buffer was empty. The caller may then
     /// decide what to do next (e.g. spin-wait, sleep, process something
-    /// else, etc)
+    /// else, etc.)
     fn try_pop(&self) -> Option<T> {
         let head = self.ccache.head.load(Ordering::Relaxed);
         let slot = unsafe { &*self.buffer_storage.add(head & self.mask) };
@@ -178,25 +178,25 @@ impl<T> Buffer<T> {
         None
     }
 
-    /// Disconnects the consumer, and returns whether or not it was already
+    /// Disconnects the consumer, and returns whether it was already
     /// disconnected
     pub(crate) fn disconnect_consumer(&self) -> bool {
         self.pcache.consumer_id.swap(usize::MAX, Ordering::Release) == usize::MAX
     }
 
-    /// Disconnects the consumer, and returns whether or not it was already
+    /// Disconnects the consumer, and returns whether it was already
     /// disconnected
     pub(crate) fn disconnect_producer(&self) -> bool {
         self.ccache.producer_id.swap(usize::MAX, Ordering::Release) == usize::MAX
     }
 
-    /// Disconnects the consumer, and returns whether or not it was already
+    /// Disconnects the consumer, and returns whether it was already
     /// disconnected
     pub(crate) fn producer_disconnected(&self) -> bool {
         self.ccache.producer_id.load(Ordering::Acquire) == usize::MAX
     }
 
-    /// Disconnects the consumer, and returns whether or not it was already
+    /// Disconnects the consumer, and returns whether it was already
     /// disconnected
     pub(crate) fn consumer_disconnected(&self) -> bool {
         self.pcache.consumer_id.load(Ordering::Acquire) == usize::MAX