[move reference] Review new docs (#35)

* prettier

* review

* Apply suggestions from code review

Co-authored-by: Cam Swords <[email protected]>

* comments

* Fix addr

* Comments

---------

Co-authored-by: Cam Swords <[email protected]>

.prettierrc

@@ -1,4 +1,9 @@
 {
   "tabWidth": 2,
-  "useTabs": false
+  "useTabs": false,
+  "printWidth": 100,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "proseWrap": "always"
 }

reference/README.md

@@ -4,35 +4,32 @@ title: Move Book
 custom_edit_url: https://github.com/move-language/move/edit/main/language/documentation/book/README.md
 ---
 
-In order to update the Move book and preview changes to it you'll need to
-install
-[`mdbook`](https://rust-lang.github.io/mdBook/guide/installation.html). You
-can do this via `cargo install mdbook`.
+In order to update the Move book and preview changes to it you'll need to install
+[`mdbook`](https://rust-lang.github.io/mdBook/guide/installation.html). You can do this via
+`cargo install mdbook`.
 
-After installing mdbook, you can preview changes via either `mdbook serve`,
-or if you want the output to change as you make changes to the book you can
-use `mdbook watch`. More information on options can be found at the [mdbook
-website](https://rust-lang.github.io/mdBook/).
+After installing mdbook, you can preview changes via either `mdbook serve`, or if you want the
+output to change as you make changes to the book you can use `mdbook watch`. More information on
+options can be found at the [mdbook website](https://rust-lang.github.io/mdBook/).
 
-Once you are happy with your changes to the Move book, you can create a PR to
-update the Move book website. This is the process that has been used in
-the past and is known to work, but there may be a better way:
+Once you are happy with your changes to the Move book, you can create a PR to update the Move book
+website. This is the process that has been used in the past and is known to work, but there may be a
+better way:
 
-1. Run `mdbook build` in this directory. This will create a directory
-called `book`. Copy this to some location `L` outside of the Move git tree.
+1. Run `mdbook build` in this directory. This will create a directory called `book`. Copy this to
+   some location `L` outside of the Move git tree.
 
 2. Make sure your upstream is up-to-date and checkout to `upstream/gh-pages`.
 
-3. Once you have checked out to `upstream/gh-pages`, make sure you are at the
-root of the repo. You should see a number of `.html` files. You can now
-move all contents in `L` to this location: `mv L/* .`
+3. Once you have checked out to `upstream/gh-pages`, make sure you are at the root of the repo. You
+   should see a number of `.html` files. You can now move all contents in `L` to this location:
+   `mv L/* .`
 
-4. Once this is done inspect things to make sure the book looks the way you
-want. If everything looks good submit a PR to the **`gh-pages`** branch of the
-main Move repo.
+4. Once this is done inspect things to make sure the book looks the way you want. If everything
+   looks good submit a PR to the **`gh-pages`** branch of the main Move repo.
 
-After this the normal PR process is followed. Once the PR has been accepted and
-lands the updated Move book should be visible immediately.
+After this the normal PR process is followed. Once the PR has been accepted and lands the updated
+Move book should be visible immediately.
 
-**NB:** When adding a new (sub)section to the book you _must_ include the new
-file in the `SUMMARY.md` file otherwise it will not appear in the updated book.
+**NB:** When adding a new (sub)section to the book you _must_ include the new file in the
+`SUMMARY.md` file otherwise it will not appear in the updated book.

reference/src/control-flow/labeled-control-flow.md

@@ -37,9 +37,9 @@ fun sum_until_threshold(input: &vector<vector<u64>>, threshold: u64): u64 {
                 // the next element we saw would break the threshold,
                 // so we return the current sum
                 break 'outer sum
-            }
+            };
             j = j + 1;
-        }
+        };
         i = i + 1;
     }
 }
@@ -54,10 +54,10 @@ that might see us continuing the inner or outer loop, we could express that code
     ...
     'inner: while (cond) {
         ...
-        if (cond0) { break 'outer value }
+        if (cond0) { break 'outer value };
         ...
         if (cond1) { continue 'inner }
-        else if (cond2) { continue 'outer }
+        else if (cond2) { continue 'outer };
         ...
     }
     ...

reference/src/functions.md

@@ -132,6 +132,21 @@ restrictions are specific to each individual deployment of Move.
 
 [The documentation for `entry` functions on Sui can be found here.](https://docs.sui.io/concepts/sui-move-concepts/entry-functions).
 
+To enable easier testing, `entry` functions can be called from
+[`#[test]` and `#[test_only]`](./unit-testing.md) contexts.
+
+```move
+module a::m {
+    entry fun foo(): u64 { 0 }
+}
+module a::m_test {
+    #[test]
+    fun my_test(): u64 { a::m::foo() } // valid!
+    #[test_only]
+    fun my_test_helper(): u64 { a::m::foo() } // valid!
+}
+```
+
 ### Name
 
 Function names can start with letters `a` to `z`. After the first character, function names can

reference/src/index-syntax.md

@@ -1,7 +1,7 @@
 # Index Syntax
 
 Move provides syntax attributes to allow you to define operations that look and feel like native
-move code, lowering these operations into your user-provided definitions.
+Move code, lowering these operations into your user-provided definitions.
 
 Our first syntax method, `index`, allows you to define a group of operations that can be used as
 custom index accessors for your datatypes, such as accessing a matrix element as `m[i,j]`, by
@@ -20,13 +20,13 @@ module matrix {
     public struct Matrix<T> { v: vector<vector<T>> }
 
     #[syntax(index)]
-    public fun borrow<T>(s: &Matrix<T>, i: u64, j: u64):  &T {
-        borrow(borrow(s.v, i), j)
+    public fun borrow<T>(s: &Matrix<T>, i: u64, j: u64): &T {
+        vector::borrow(vector::borrow(&s.v, i), j)
     }
 
     #[syntax(index)]
-    public fun borrow_mut<T>(s: &mut Matrix<T>, i: u64, j: u64):  &mut T {
-        borrow_mut(borrow_mut(s.v, i), j)
+    public fun borrow_mut<T>(s: &mut Matrix<T>, i: u64, j: u64): &mut T {
+        vector::borrow_mut(vector::borrow_mut(&mut s.v, i), j)
     }
 
     public fun make_matrix<T>(v: vector<vector<T>>):  Matrix<T> {
@@ -39,20 +39,20 @@ module matrix {
 Now anyone using this `Matrix` type has access to index syntax for it:
 
 ```move
-let v0 = vector<u64>[1, 0, 0];
-let v1 = vector<u64>[0, 1, 0];
-let v2 = vector<u64>[0, 0, 1];
-let v = vector<vector<u64>>[v0, v1, v2];
-let mut m = matrix::make_matrix(v);
+let mut m = matrix::make_matrix(vector[
+    vector[1, 0, 0],
+    vector[0, 1, 0],
+    vector[0, 0, 1],
+]);
 
 let mut i = 0;
 while (i < 3) {
     let mut j = 0;
     while (j < 3) {
         if (i == j) {
-            assert!(m[i, j] == 1, i);
+            assert!(m[i, j] == 1, 1);
         } else {
-            assert!(m[i, j] == 0, i + 10);
+            assert!(m[i, j] == 0, 0);
         };
         *(&mut m[i,j]) = 2;
         j = j + 1;
@@ -78,13 +78,13 @@ the position and mutable usage of the expression:
 let mut mat = matrix::make_matrix(...);
 
 let m_0_0 = mat[0, 0];
-    // translates to copy matrix::borrow(&mat, 0, 0)
+// translates to `copy matrix::borrow(&mat, 0, 0)`
 
 let m_0_0 = &mat[0, 0];
-    // translates to matrix::borrow(&mat, 0, 0)
+// translates to `matrix::borrow(&mat, 0, 0)`
 
 let m_0_0 = &mut mat[0, 0];
-    // translates to matrix::borrow_mut(&mut mat, 0, 0)
+// translates to `matrix::borrow_mut(&mut mat, 0, 0)`
 ``
 
 You can also intermix index expressions with field accesses:
@@ -95,8 +95,8 @@ public struct V { v: vector<u64> }
 public struct Vs { vs: vector<V> }
 
 fun borrow_first(input: &Vs): &u64 {
-    input.vs[0].v[0]
-    // translates to vector::borrow(vector::borrow(input.vs, 0).v, 0)
+    &input.vs[0].v[0]
+    // translates to `vector::borrow(&vector::borrow(&input.vs, 0).v, 0)`
 }
 ````
 
@@ -111,21 +111,21 @@ structure that takes a default value if the index is out of bounds:
 #[syntax(index)]
 public fun borrow_or_set<Key: copy, Value: drop>(
     input: &mut MTable<Key, Value>,
-    key: &Key,
+    key: Key,
     default: Value
 ): &mut Value {
-    if (contains(input, *key)) {
+    if (contains(input, key)) {
         borrow(input, key)
     } else {
-        insert(input, *key, default)
+        insert(input, key, default);
         borrow(input, key)
     }
 }
 ```
 
 Now, when you index into `MTable`, you must also provide a default value:
 
-```
+```move
 let string_key: String = ...;
 let mut table: MTable<String, u64> = m_table::make_table();
 let entry: &mut u64 = &mut table[string_key, 0];
@@ -167,9 +167,7 @@ defined in `std::vector` is an example of this:
 
 ```move
 #[syntax(index)]
-public fun borrow<Element>(v: &vector<Element>, i: u64): &Element {
-    // implementation
-}
+public native fun borrow<Element>(v: &vector<Element>, i: u64): &Element;
 ```
 
 #### Mutable Accessor
@@ -180,9 +178,7 @@ element type. The `borrow_mut` function defined in `std::vector` is an example o
 
 ```move
 #[syntax(index)]
-public fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element {
-    // implementation
-}
+public native fun borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element;
 ```
 
 #### Visibility
@@ -242,7 +238,7 @@ whose subject and return mutability differ:
 #[syntax(index)]
 public fun borrow_imm(x: &mut Matrix<u64>, ...): &u64 { ... }
     // ERROR! incompatible mutability
-
+    // expected a mutable reference '&mut' return type
 ```
 
 ### Type Compatibility
@@ -264,32 +260,32 @@ To illustrate some of these errors, recall the previous `Matrix` definition:
 
 ```move
 #[syntax(index)]
-public fun borrow<T>(s: &Matrix<T>, i: u64, j: u64):  &T {
-    borrow(borrow(s.v, i), j)
+public fun borrow<T>(s: &Matrix<T>, i: u64, j: u64): &T {
+    vector::borrow(vector::borrow(&s.v, i), j)
 }
 ```
 
 All of the following are type-incompatible definitions of the mutable version:
 
 ```move
 #[syntax(index)]
-public fun borrow_mut<T: drop>(s: &mut Matrix<T>, i: u64, j: u64):  &mut T { ... }
+public fun borrow_mut<T: drop>(s: &mut Matrix<T>, i: u64, j: u64): &mut T { ... }
     // ERROR! `T` has `drop` here, but no in the immutable version
 
 #[syntax(index)]
-public fun borrow_mut(s: &mut Matrix<u64>, i: u64, j: u64):  &mut u64 { ... }
+public fun borrow_mut(s: &mut Matrix<u64>, i: u64, j: u64): &mut u64 { ... }
     // ERROR! This takes a different number of type parameters
 
 #[syntax(index)]
-public fun borrow_mut<T, U>(s: &mut Matrix<U>, i: u64, j: u64):  &mut U { ... }
+public fun borrow_mut<T, U>(s: &mut Matrix<U>, i: u64, j: u64): &mut U { ... }
     // ERROR! This takes a different number of type parameters
 
 #[syntax(index)]
-public fun borrow_mut<T, U>(s: &mut Matrix<U>, i_j: (u64, u64)):  &mut U { ... }
+public fun borrow_mut<U>(s: &mut Matrix<U>, i_j: (u64, u64)): &mut U { ... }
     // ERROR! This takes a different number of arguments
 
 #[syntax(index)]
-public fun borrow_mut<T, U>(s: &mut Matrix<U>, i: u64, j: u32):  &mut U { ... }
+public fun borrow_mut<U>(s: &mut Matrix<U>, i: u64, j: u32): &mut U { ... }
     // ERROR! `j` is a different type
 ```