From 8557f5992ad414c29b93d9e318490eb0b8cebc54 Mon Sep 17 00:00:00 2001
From: Eskil Heyn Olsen <eskil@eskil.org>
Date: Sun, 4 Feb 2024 15:35:31 -0800
Subject: [PATCH] Docs improvements

---
 Quickstart.md | 33 ++++++++++++++++++++++++++-------
 README.md     |  7 +++++--
 2 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/Quickstart.md b/Quickstart.md
index 8730730..b01dda1 100644
--- a/Quickstart.md
+++ b/Quickstart.md
@@ -9,12 +9,20 @@ There's four steps to do a 2D polygon map path search
 1. Extend the graph with your start and stop
 1. Use Astar to find a path
 
+You can try out the code below in iex.
+
+```shell
+iex -S mix
+```
+
 ```elixir
 alias Scurry.PolygonMap
 alias Scurry.Vector
 alias Scurry.Astar
 
-## Step 1
+## Step 1 - define the world
+
+# The world is defined by a boundary box plus holes inside the box.
 
 # World boundary
 polygon = [{0, 0}, {100, 0}, {100, 100}, {0, 100}]
@@ -25,13 +33,14 @@ holes = [
  [{60, 30}, {70, 30}, {70, 70}, {60, 70}],
 ]
 
-## Step 2
+## Step 2 - convert world to graph
 
-# The cost function for the graph, euclidian distance
-cost_fun = fn a, b -> Vector.distance(a, b) end
+# To compute a path, we need to convert the boundary & holes into
+# a graph of all corners.
 
-# The heuristic function for A-star, euclidian distance as well
-heur_fun = fn a, b -> Vector.distance(a, b) end
+# The cost function for the graph, this uses basic euclidian distance
+# as a basic example. This is used to compute the graph of the world.
+cost_fun = fn a, b -> Vector.distance(a, b) end
 
 # Find the reachable vertices
 vertices = PolygonMap.get_vertices(polygon, holes)
@@ -39,7 +48,10 @@ vertices = PolygonMap.get_vertices(polygon, holes)
 # Make a graph of them using an optional cost_fun
 graph = PolygonMap.create_graph(polygon, holes, vertices, cost_fun)
 
-## Step 3
+## Step 3 - extend graph with actor start/stop
+
+# For an actor to move from a to b in the world, we first extend the
+# graph with start and stop
 
 # Define our start & stop
 {start, stop} = {{10, 10}, {90, 90}}
@@ -51,6 +63,13 @@ graph = PolygonMap.create_graph(polygon, holes, vertices, cost_fun)
 
 ## Step 4
 
+# Given the new graph, finally compute the path in the world.
+
+# The heuristic function for A-star, this uses euclidian distance as well.
+# This is used as the cost of each edge traversal in the graph during a-star
+# path finding. It can be the same as cost_fun but it does not have to be.
+heur_fun = fn a, b -> Vector.distance(a, b) end
+
 # Astar search
 astar = Astar.search(search_graph, start, stop, heur_fun)
 path = Astar.path(astar)
diff --git a/README.md b/README.md
index 96de9ea..6eebf40 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ $ mix deps.get
 
 ## Internals
 
-There's better API documentation than this see [the hexdocs](https://hexdocs.pm/scurry).
+*There's better API documentation than this see [the hexdocs](https://hexdocs.pm/scurry), especially see the [quickstart](Quickstart.md).*
 
 ```
 mix docs
@@ -183,7 +183,10 @@ determine if two vertices should have an edge. This is currently not
 configurable or passed as a function.
 
 The default `cost_fun` and `heur_fun` is the euclidean distance been
-the two points.
+the two points. The difference between the two is, `cost_fun` is used
+while computing the graph and `heur_fun` while computing the
+path. Typically they will be the same but that is dependent on use
+case.
 
 ```elixir
 cost_fun = fn a, b -> Vector.distance(a, b) end