Docs and stuff

Signed-off-by: Klimenty Tsoutsman <klim@tsoutsman.com>

applications/shell/Cargo.toml

@@ -19,9 +19,6 @@ path = "../../libs/keycodes_ascii"
 path = "../../libs/dfqueue"
 version = "0.1.0"
 
-[dependencies.event_types]
-path = "../../kernel/event_types"
-
 [dependencies.spawn]
 path = "../../kernel/spawn"
 

kernel/_doc_root.rs

@@ -24,7 +24,6 @@
 //! * `ata_pio`: Support for ATA hard disks (IDE/PATA) using PIO (not DMA), and not SATA.
 //! * `captain`: The main driver of Theseus. Controls the loading and initialization of all subsystems and other crates.
 //! * `compositor`: The trait of a compositor. It composites a list of buffers to a final buffer.
-//! * `event_types`: The types used for passing input and output events across the system.
 //! * `device_manager`: Code for handling the sequence required to initialize each driver.
 //! * `displayable`: Defines a displayable trait. A displayable can display itself in a framebuffer.
 //! * `text_display`: A text display is a displayable. It contains a block of text and can display in a framebuffer.

kernel/async_channel/src/lib.rs

@@ -11,6 +11,13 @@ use mpmc::Queue;
 use sync::DeadlockPrevention;
 use sync_spin::Spin;
 
+/// A bounded, multi-producer, multi-consumer asynchronous channel.
+///
+/// The channel can also be used outside of an asynchronous runtime with the
+/// [`blocking_send`], and [`blocking_recv`] methods.
+///
+/// [`blocking_send`]: Self::blocking_send
+/// [`blocking_recv`]: Self::blocking_recv
 #[derive(Clone)]
 pub struct Channel<T, P = Spin>
 where
@@ -27,6 +34,28 @@ where
     T: Send,
     P: DeadlockPrevention,
 {
+    /// Creates a new channel.
+    ///
+    /// The provided capacity dictates how many messages can be stored in the
+    /// queue before the sender blocks.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use async_channel::Channel;
+    ///
+    /// let channel = Channel::new(2);
+    ///
+    /// assert!(channel.try_send(1).is_ok());
+    /// assert!(channel.try_send(2).is_ok());
+    /// // The channel is full.
+    /// assert!(channel.try_send(3).is_err());
+    ///
+    /// assert_eq!(channel.try_recv(), Some(1));
+    /// assert_eq!(channel.try_recv(), Some(2));
+    /// assert!(channel.try_recv().is_none());
+    /// ```
+    // TODO: Is a capacity of 0 = rendezvous?
     pub fn new(capacity: usize) -> Self {
         Self {
             inner: Queue::with_capacity(capacity),
@@ -35,6 +64,13 @@ where
         }
     }
 
+    /// Sends `value`.
+    ///
+    /// # Cancel safety
+    ///
+    /// This method is cancel safe, in that if it is dropped prior to
+    /// completion, `value` is guaranteed to have not been set. However, in that
+    /// case `value` will be dropped.
     pub async fn send(&self, value: T) {
         let mut temp = Some(value);
 
@@ -52,20 +88,37 @@ where
             .await
     }
 
+    /// Tries to send `value`.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error containing `value` if the channel was full.
     pub fn try_send(&self, value: T) -> Result<(), T> {
         self.inner.push(value)
     }
 
+    /// Blocks the current thread until `value` is sent.
     pub fn blocking_send(&self, value: T) {
         dreadnought::block_on(self.send(value))
     }
 
+    /// Receives the next value.
+    ///
+    /// # Cancel safety
+    ///
+    /// This method is cancel safe.
     pub async fn recv(&self) -> T {
         let value = self.receivers.wait_until(|| self.inner.pop()).await;
         self.senders.notify_one();
         value
     }
 
+    /// Tries to receive the next value.
+    pub fn try_recv(&self) -> Option<T> {
+        self.inner.pop()
+    }
+
+    /// Blocks the current thread until a value is received.
     pub fn blocking_recv(&self) -> T {
         dreadnought::block_on(self.recv())
     }
@@ -98,6 +151,7 @@ where
     P: DeadlockPrevention,
 {
     fn is_terminated(&self) -> bool {
+        // NOTE: If we ever implement disconnections, this will need to be modified.
         false
     }
 }

kernel/compositor/Cargo.toml

@@ -6,12 +6,13 @@ edition = "2021"
 [dependencies]
 async_channel = { path = "../async_channel" }
 dreadnought = { path = "../dreadnought" }
-event_types = { path = "../event_types" }
 futures = { version = "0.3.28", default-features = false, features = ["async-await"] }
 graphics = { path = "../graphics" }
 hashbrown = "0.11.2"
+keyboard = { path = "../keyboard" }
 log = "0.4.8"
 memory = { path = "../memory" }
+mouse = { path = "../mouse" }
 sync_spin = { path = "../../libs/sync_spin" }
 waker = { path = "../waker" }
 # TODO: Update to 0.7.8