From 1b4867545111a4ec920de7b0a58bca489cefd675 Mon Sep 17 00:00:00 2001
From: Adrien Burgun <adrien.burgun@orange.fr>
Date: Tue, 21 Jun 2022 14:51:56 +0200
Subject: [PATCH] :pencil: Some more documentation

---
 .github/workflows/rustdoc.yaml | 38 ++++++++++++++++++++++++
 stackline/src/context.rs       | 53 +++++++++++++++++++++++++++++-----
 2 files changed, 83 insertions(+), 8 deletions(-)
 create mode 100644 .github/workflows/rustdoc.yaml

diff --git a/.github/workflows/rustdoc.yaml b/.github/workflows/rustdoc.yaml
new file mode 100644
index 0000000..c367390
--- /dev/null
+++ b/.github/workflows/rustdoc.yaml
@@ -0,0 +1,38 @@
+name: rustdoc
+on:
+  push:
+   branches:
+   - master
+
+env:
+  CARGO_INCREMENTAL: 0
+  CARGO_NET_RETRY: 10
+  RUSTUP_MAX_RETRIES: 10
+
+jobs:
+  rustdoc:
+    if: github.repository == 'adri326/stackline2'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Install Rust toolchain
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        profile: minimal
+        override: true
+        components: rustfmt, rust-src
+
+    - name: Build Documentation
+      run: cargo doc --all --no-deps
+
+    - name: Deploy Docs
+      uses: peaceiris/actions-gh-pages@364c31d33bb99327c77b3a5438a83a357a6729ad # v3.4.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: gh-pages
+        publish_dir: ./target/doc
+        force_orphan: true
diff --git a/stackline/src/context.rs b/stackline/src/context.rs
index c381af1..d3958d2 100644
--- a/stackline/src/context.rs
+++ b/stackline/src/context.rs
@@ -3,10 +3,52 @@ use super::*;
 /** Provides an interface between a [`Tile`] and its parent [`Pane`] during [`Tile::update`].
     All actions performed through `UpdateContext` will be executed *after* all the tiles have updated.
 
+    ## Design
+
+    There are several factors that come into the design of [`UpdateContext`]:
+
+    - all of its methods are considered hot-path code, which means that allocations must be kept at a minimum
+    - all of the actions must be performed after all the tiles were updated
+    - we need mutable access to the current tile, so that it can update its internal state
+
+    ## Example
+
+    ```
+    # use stackline::{*, tile::*, context::*};
+
+    #[derive(Clone, Debug)]
+    pub struct CounterTile(usize);
+
+    impl CounterTile {
+        pub fn new() -> Self {
+            Self(0)
+        }
+    }
+
+    impl Tile for CounterTile {
+        fn update<'b>(&'b mut self, mut ctx: UpdateContext<'b>) {
+            if let Some(signal) = ctx.take_signal() {
+                // Update the internal state
+                self.0 += 1;
+
+                // Send the signal along: first, get the offset (Δx, Δy) associated with its direction and the tile at (x+Δx,y+Δy)
+                if let Some((pos, tile)) = ctx.get_offset(signal.direction().into_offset()) {
+                    // Then, check that `tile` accepts signals
+                    if tile.accepts_signal(signal.direction()) {
+                        // Finally, send the signal
+                        ctx.send(pos, signal).unwrap_or_else(|| unreachable!());
+                    }
+                }
+            }
+        }
+    }
+
+    ```
+
     ## Safety
 
-    Because [`Tile::update`] requires a `&mut self` reference, the current [`Tile`] cannot be accessed through [`UpdateContext::get`]
-    This structure stores the state and signal of the [`FullTile`] containing the current tile, and it is still possible and safe to call [`UpdateContext::send`] on the current position.
+    Because [`Tile::update`] requires a `&mut self` reference, the current [`Tile`] cannot be accessed through [`UpdateContext::get`].
+    This structure stores the [`State`] and [`Signal`] of the [`FullTile`] containing the current tile, so these can be accessed nonetheless, and it is still possible and safe to call [`UpdateContext::send`] on the current position.
 **/
 pub struct UpdateContext<'a> {
     position: (usize, usize),
@@ -62,12 +104,7 @@ impl<'a> UpdateContext<'a> {
         std::mem::take(&mut self.signal)
     }
 
-    // #[inline]
-    // pub fn set_signal(&mut self, signal: Option<Signal>) {
-    //     *self.signal = signal;
-    // }
-
-    /// Returns the state of the current tile.
+    /// Returns the [`State`] of the current tile.
     #[inline]
     pub fn state(&self) -> State {
         self.state