Add examples of calling two algorithms to README (#293)

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.

Author: natebosch

pkgs/graphs/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## 2.3.3-wip
 
+- Add an example usage to the README.
+
 ## 2.3.2
 
 - Require Dart 3.4

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);
+}
+```