Update documentation (#2074)

Cargo.toml

@@ -14,6 +14,7 @@ members = [
   "device",
   "dynamic",
   "engine",
+  "examples/custom-vm",
   "examples/embedded-script",
   "examples/hot-reload",
   "examples/no-std-no-alloc",

README.md

@@ -19,6 +19,14 @@ For more information and usage, visit [the full documentation](https://raviqqe.g
 
 ## Install
 
+### Interpreter
+
+To install the Scheme interpreter as a command, run:
+
+```sh
+cargo install stak
+```
+
 ### Libraries
 
 To install Stak Scheme as a library in your Rust project, run:
@@ -31,40 +39,49 @@ cargo install stak-compile
 
 For full examples, see [the `examples` directory](https://github.com/raviqqe/stak/tree/main/examples).
 
-### Command line tools
-
-To install the Scheme interpreter as a command, run:
-
-```sh
-cargo install stak
-```
-
 ## Examples
 
 ### Dynamic scripting in Rust
 
 First, prepare a Scheme script named `src/fight.scm`:
 
 ```scheme
+; Import a base library and the library named `(stak rust)` for Rust integration.
 (import (scheme base) (stak rust))
 
+; Use the `define-rust` procedure to import native functions written in Rust.
+; The order of the functions should match the ones passed into the `Engine::new()`
+; function in Rust.
 (define-rust
   make-person
-  person-throw-pie
-  person-wasted)
+  person-pies
+  person-wasted
+  person-throw-pie)
 
+; Make two people with a number of pies they have and their dodge rates.
 (define me (make-person 4 0.2))
-(define you (make-person 2 0.6))
-
-(person-throw-pie me you)
-(person-throw-pie you me)
-(person-throw-pie me you)
-(person-throw-pie you me)
-
-(when (person-wasted you)
-  (write-string "Congrats!"))
-(when (person-wasted me)
-  (write-string "Oh, no!"))
+(define friend (make-person 2 0.6))
+
+; The fight begins. Let's throw pies to each other!
+(do ()
+  ((or
+      (person-wasted me)
+      (person-wasted friend)
+      (and
+        (zero? (person-pies me))
+        (zero? (person-pies friend)))))
+  (person-throw-pie me friend)
+  (person-throw-pie friend me))
+
+; Output the winner.
+(write-string
+  (cond
+    ((person-wasted friend)
+      "You won!")
+    ((person-wasted me)
+      "You lost...")
+    (else
+      "Draw...")))
 ```
 
 Then, add a build script at `build.rs` to build the Scheme source file
@@ -92,13 +109,15 @@ use stak::{
 
 const HEAP_SIZE: usize = 1 << 16;
 
+/// A person who holds pies to throw.
 struct Person {
     pies: usize,
     dodge: f64,
     wasted: bool,
 }
 
 impl Person {
+    /// Creates a person.
     pub fn new(pies: usize, dodge: f64) -> Self {
         Self {
             pies,
@@ -107,12 +126,19 @@ impl Person {
         }
     }
 
+    /// Returns a number of pies the person has.
+    pub fn pies(&self) -> usize {
+        self.pies
+    }
+
+    /// Returns `true` if a person is wasted.
     pub fn wasted(&self) -> bool {
         self.wasted
     }
 
+    /// Throws a pie to another person.
     pub fn throw_pie(&mut self, other: &mut Person) {
-        if self.wasted {
+        if self.pies == 0 || self.wasted {
             return;
         }
 
@@ -125,22 +151,29 @@ impl Person {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
+    // Import a Scheme module of the script.
     static MODULE: UniversalModule = include_module!("fight.scm");
 
-    run(&MODULE)?;
+    // Run the Scheme module.
+    run_scheme(&MODULE)?;
 
     Ok(())
 }
 
-fn run(module: &'static UniversalModule) -> Result<(), EngineError> {
+fn run_scheme(module: &'static UniversalModule) -> Result<(), EngineError> {
+    // Initialize a heap memory for a Scheme scripting engine.
     let mut heap = [Default::default(); HEAP_SIZE];
+    // Define Rust functions to pass to the engine.
     let mut functions = [
         r#fn(Person::new),
-        r#fn(Person::throw_pie),
+        r#fn::<(Ref<_>,), _>(Person::pies),
         r#fn::<(Ref<_>,), _>(Person::wasted),
+        r#fn(Person::throw_pie),
     ];
+    // Initialize the engine.
     let mut engine = Engine::new(&mut heap, &mut functions)?;
 
+    // Finally, run the module!
     engine.run(module)
 }
 ```

doc/astro.config.ts

@@ -97,6 +97,10 @@ export default defineConfig({
               label: "Embedding Scheme in Rust",
               link: "/embedding-scripts",
             },
+            {
+              label: "Running in no-std and no-alloc environment",
+              link: "/no-std-no-alloc",
+            },
             {
               label: "Hot reloading",
               link: "/hot-reload",
@@ -105,10 +109,6 @@ export default defineConfig({
               label: "Writing a Scheme subset",
               link: "/writing-scheme-subset",
             },
-            {
-              label: "No-std and no-alloc support",
-              link: "/no-std-no-alloc",
-            },
           ],
         },
         {