From 2047e0bf82469f0bed318670c7f0fc2f45c42edf Mon Sep 17 00:00:00 2001
From: Jeff <dev@jeffa.io>
Date: Fri, 2 Aug 2024 15:10:29 -0400
Subject: [PATCH] Add some docs and clean up example

---
 README.md                    | 89 ++++++++++++++++++++++++++++--------
 dust_examples/async_count.ds | 14 +++---
 2 files changed, 76 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index ebbd6e3..d3b2464 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,80 @@
 # Dust
 
-High-level programming language with effortless concurrency, automatic memory management, type
-safety and familiar syntax.
+High-level programming language with effortless concurrency, automatic memory management and type
+safety.
+
+## Concepts
+
+Dust is heavily influenced by Rust, but aims to be more high-level and easier to use. Its approach
+to safety is similar in that it will refuse to run programs with issues that can be caught by
+static analysis. However, Dust is not compiled and while performance is a concern, it is less
+important than safety and ease of use.
+
+### Effortless Concurrency
+
+Rust promises *fearless* concurrency, and Dust takes it a step further by making concurrency as
+simple as possible. Dust is organized into **statements**, and any sequence of statements can be
+run concurrently by simply adding the `async` keyword before the block of statements.
 
 ```dust
-io.write_line("Guess the number.")
+# This function will count from 0 to 9, sleeping for an increasing amount of
+# time between each number.
+count_slowly = fn (
+	multiplier: int,
+) {
+	i = 0
 
-secret_number = random.in_range(0..100)
+	while i < 10 {
+		sleep_time = i * multiplier;
 
-loop {
-  	io.write_line("Input your guess.")
+		thread.sleep(sleep_time)
+		thread.write_line(i as str)
 
-  	input = io.read_line().expect("Failed to read line.")
-  	guess = match input.trim().parse() {
-    	Ok(value) => value,
-      Err(_) => continue,
-    }
+		i += 1
+	}
+}
 
-  	if guess < secret_number {
-  	  	io.write_line("Too low!")
-	  } else if guess > secret_number {
-	    	io.write_line("Too high!")
-	  } else {
-	    	io.write_line("You win!")
-	    	break
-	  }
+async {
+	count_slowly(200) # Finishes last
+	count_slowly(100) # Finishes seconds
+	count_slowly(50)  # Finishes first
 }
 ```
+
+### Automatic Memory Management
+
+Dust uses a garbage collector to automatically manage memory. During the analysis phase, Dust will
+determine the number of references to each value. During execution, the intepreter will check the
+context after each statement and remove values that will not be used again.
+
+```dust
+x = 0 # x is assigned but never used
+      # x is removed from memory
+
+y = 41 # y is assigned
+y + 1  # y is kept alive for this statement
+       # y is removed from memory
+```
+
+### Type Safety
+
+Dust is statically typed and null-free, but the type of a value can usually be inferred from its
+usage. Dust will refuse to run programs with type errors, but will usually not require type
+annotations.
+
+```dust
+# These two statements are identical to Dust
+x = 1
+x: int = 1
+
+# Numbers with decimals are floats
+y = 10.0
+y: float = 10.0
+
+# Strings are enclosed in single or double quotes and are guaranteed to be valid UTF-8
+z = "Hello, world!"
+z: string = "Hello, world!"
+```
+
+Aside from the ubiqutous `bool`, `int`, `float`, and `string` types, Dust also has `list`, `map`,
+`range`, structures, enums and functions.
diff --git a/dust_examples/async_count.ds b/dust_examples/async_count.ds
index 699291c..8b6038f 100644
--- a/dust_examples/async_count.ds
+++ b/dust_examples/async_count.ds
@@ -1,23 +1,21 @@
 count_slowly = fn (
 	multiplier: int,
-	sleep: fn (milliseconds: int),
-	write_line: fn (output: str),
 ) {
 	i = 0
 
 	while i < 10 {
 		sleep_time = i * multiplier;
 
-		sleep(sleep_time)
-		write_line(i as str)
+		thread.sleep(sleep_time)
+		thread.write_line(i as str)
 
 		i += 1
 	}
 }
 
 async {
-	count_slowly(50, thread.sleep, io.write_line)
-	count_slowly(100, thread.sleep, io.write_line)
-	count_slowly(200, thread.sleep, io.write_line)
-	count_slowly(250, thread.sleep, io.write_line)
+	count_slowly(50)
+	count_slowly(100)
+	count_slowly(200)
+	count_slowly(250)
 }