From e86b4bd7e3f2fe1b38bffb1fa78a19f0391e7c3d Mon Sep 17 00:00:00 2001
From: Nate Bosch <nbosch@google.com>
Date: Wed, 14 Aug 2024 18:05:36 +0000
Subject: [PATCH 1/2] Add examples of calling two algorithms to README

Closes #103

Reword most of the README.
- Use "callback" consistently to describe the arguments to the
  algorithms.
- Add generics and more specific names to the tiny example data
  structures.
- Use consistent phrasing in the bullet points about the types of
  callbacks needed.
- Reorder the bullet points since the edges callbacks are always used
  and worth mentioning first.

Add a code block with skeleton examples of calls using each of the
example data structures. One example of calls `shortestPath` on a graph
with adjacency lists stored in a `Map` using terms related to
networking. The other calls `topologicalSort` on a graph represented by
a tree of node objects which store outgoing edges using terms related to
build dependencies.
---
 pkgs/graphs/CHANGELOG.md |  4 +++
 pkgs/graphs/README.md    | 59 +++++++++++++++++++++++++---------------
 pkgs/graphs/pubspec.yaml |  2 +-
 3 files changed, 42 insertions(+), 23 deletions(-)

diff --git a/pkgs/graphs/CHANGELOG.md b/pkgs/graphs/CHANGELOG.md
index 6d0c36c7e..7213b5a22 100644
--- a/pkgs/graphs/CHANGELOG.md
+++ b/pkgs/graphs/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.3.3-wip
+
+- Add an example usage to the README.
+
 ## 2.3.2
 
 - Require Dart 3.4
diff --git a/pkgs/graphs/README.md b/pkgs/graphs/README.md
index 2bf0eec6a..85e1204d2 100644
--- a/pkgs/graphs/README.md
+++ b/pkgs/graphs/README.md
@@ -5,38 +5,53 @@
 Graph algorithms that do not specify a particular approach for representing a
 Graph.
 
-Functions in this package will take arguments that provide the mechanism for
-traversing the graph. For example two common approaches for representing a
-graph:
+Each algorithm is a top level function which takes callback arguments that
+provide the mechanism for traversing the graph. For example two common
+approaches for representing a graph:
 
 ```dart
-class Graph {
-  Map<Node, List<Node>> nodes;
-}
-class Node {
-  // Interesting data
+class AdjacencyListGraph<T> {
+  Map<T, List<T>> nodes;
+  // ...
 }
 ```
 
 ```dart
-class Graph {
-  Node root;
+class TreeGraph<T> {
+  Node<T> root;
+  // ...
 }
-class Node {
-  List<Node> edges;
-  // Interesting data
+class Node<T> {
+  List<Node<T>> edges;
+  T value;
 }
 ```
 
-Any representation can be adapted to the needs of the algorithm:
+Any representation can be adapted to the callback arguments.
+
+- Algorithms which need to traverse the graph take an `edges` callback which
+  provides the immediate neighbors of a given node.
+- Algorithms which need to associate unique data with each node in the graph
+  allow passing `equals` and/or `hashCode` callbacks if the unique data type
+  does not correctly or efficiently implement `operator==` or `get hashCode`.
+
+
+Algorithms that support graphs which are resolved asynchronously will have
+similar callbacks which return `FutureOr`.
 
-- Some algorithms need to associate data with each node in the graph. If the
-  node type `T` does not correctly or efficiently implement `hashCode` or `==`,
-  you may provide optional `equals` and/or `hashCode` functions are parameters.
-- Algorithms which need to traverse the graph take a `edges` function which provides the reachable nodes.
-  - `(node) => graph[node]`
-  - `(node) => node.edges`
+```dart
+import 'package:graphs/graphs.dart';
 
+void sendMessage() {
+  final network = AdjacencyListGraph();
+  // ...
+  final route = shortestPath(
+      sender, receiver, (node) => network.nodes[node] ?? const []);
+}
 
-Graphs that are resolved asynchronously will have similar functions which
-return `FutureOr`.
+void resolveBuildOrder() {
+  final dependencies = TreeGraph();
+  // ...
+  final buildOrder = topologicalSort([dependencies.root], (node) => node.edges);
+}
+```
diff --git a/pkgs/graphs/pubspec.yaml b/pkgs/graphs/pubspec.yaml
index 3696467d3..5b5457a75 100644
--- a/pkgs/graphs/pubspec.yaml
+++ b/pkgs/graphs/pubspec.yaml
@@ -1,5 +1,5 @@
 name: graphs
-version: 2.3.2
+version: 2.3.3-wip
 description: Graph algorithms that operate on graphs in any representation.
 repository: https://github.com/dart-lang/tools/tree/main/pkgs/graphs
 

From 7de678654e22ae53d800e4710b9d1bc82e18d958 Mon Sep 17 00:00:00 2001
From: Nate Bosch <nbosch@google.com>
Date: Wed, 14 Aug 2024 21:48:28 +0000
Subject: [PATCH 2/2] Add a comma

---
 pkgs/graphs/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkgs/graphs/README.md b/pkgs/graphs/README.md
index 85e1204d2..09512b87a 100644
--- a/pkgs/graphs/README.md
+++ b/pkgs/graphs/README.md
@@ -6,7 +6,7 @@ Graph algorithms that do not specify a particular approach for representing a
 Graph.
 
 Each algorithm is a top level function which takes callback arguments that
-provide the mechanism for traversing the graph. For example two common
+provide the mechanism for traversing the graph. For example, two common
 approaches for representing a graph:
 
 ```dart