Add documentation

src/move/README.md

@@ -0,0 +1,21 @@
+<!-- cspell:word entr -->
+
+# Move source code
+
+## Useful commands
+
+1. Run coverage testing and format source code on file change:
+
+   ```sh
+   git ls-files | entr -c sh -c " \
+       aptos move test --dev --move-2 --coverage &&
+       aptos move fmt
+   "
+   ```
+
+1. Display coverage against bytecode on file change:
+
+   ```sh
+   git ls-files | entr -c aptos move coverage bytecode --dev --move-2 \
+       --module <MODULE>
+   ```

src/move/research/red-black-map/README.md

@@ -8,6 +8,6 @@ The `variants` directory contains several implementations based on
 | Variant | Description                                                  |
 | ------- | ------------------------------------------------------------ |
 | `a`     | Initial unfinished attempt, with ad hoc implementation stubs |
-| `b`     | Designed to closely mimic the [Wikipedia guide]              |
+| `b`     | Closely mimics the [Wikipedia guide], uses `u32` keys        |
 
 [wikipedia guide]: https://en.wikipedia.org/wiki/Red%E2%80%93black_tree

src/move/research/red-black-map/variants/b/sources/red_black_map.move

@@ -1,4 +1,6 @@
-/// Based on Wikipedia reference implementation of red-black tree.
+/// Based on Wikipedia reference implementation of red-black tree. See Wikipedia for additional
+/// background information, diagrams, explanation of cases like `Case_I1` and `Case_D6`, and
+/// reference source code in C++ that is currently referenced in some below source code comments.
 ///
 /// # Tree notation
 ///
@@ -783,7 +785,7 @@ module red_black_map::red_black_map {
             if (sibling_ref.color is Color::Black) continue; // From now on is case D3.
             close_nephew_index = sibling_ref.children[child_direction];
 
-            // Simluate check that triggers Case_D6.
+            // Simulate check that triggers Case_D6.
             new_distant_nephew_index = nodes_ref[close_nephew_index].children[1
                 - child_direction];
             if (new_distant_nephew_index != NIL
@@ -1494,7 +1496,7 @@ module red_black_map::red_black_map {
         };
         map.destroy_empty();
 
-        // Repeat for key groups removed by first occurence of non-root black leaves.
+        // Repeat for key groups removed by first occurrence of non-root black leaves.
         let (map, _) = set_up_tree_5();
         loop {
             let node_index = map.first_case_black_non_root_leaf_node_index();