follow up, whoopsie

book/src/move-basics/comments.md

@@ -20,15 +20,11 @@ comment.
 
 ## Line comment
 
-```Move
-{{#include ../../../packages/samples/sources/move-basics/comments.move:line}}
-```
-
 You can use double slash `//` to comment out the rest of the line. Everything after `//` will be
 ignored by the compiler.
 
 ```Move
-{{#include ../../../packages/samples/sources/move-basics/comments.move:line_2}}
+{{#include ../../../packages/samples/sources/move-basics/comments-line.move:main}}
 ```
 
 ## Block comment
@@ -38,7 +34,7 @@ Everything between `/*` and `*/` will be ignored by the compiler. You can use bl
 comment out a single line or multiple lines. You can even use them to comment out a part of a line.
 
 ```Move
-{{#include ../../../packages/samples/sources/move-basics/comments.move:block}}
+{{#include ../../../packages/samples/sources/move-basics/comments-block.move:main}}
 ```
 
 This example is a bit extreme, but it shows how you can use block comments to comment out a part of
@@ -51,7 +47,7 @@ They are similar to block comments, but they start with three slashes `///` and
 the definition of the item they document.
 
 ```Move
-{{#include ../../../packages/samples/sources/move-basics/comments.move:doc}}
+{{#include ../../../packages/samples/sources/move-basics/comments-doc.move:main}}
 ```
 
 <!-- TODO: docgen, which members are in the documentation -->

book/src/move-basics/constants.md

@@ -24,7 +24,7 @@ price for a product, you might define a constant for it. Constants are stored in
 bytecode, and each time they are used, the value is copied.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/constants.move:shop_price}}
+{{#include ../../../packages/samples/sources/move-basics/constants-shop-price.move:shop_price}}
 ```
 
 ## Naming Convention
@@ -35,7 +35,7 @@ It's a way to make constants stand out from other identifiers in the code. One e
 [error constants](./assert-and-abort.md#assert-and-abort), which are written in ECamelCase.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/constants.move:naming}}
+{{#include ../../../packages/samples/sources/move-basics/constants-naming.move:naming}}
 ```
 
 ## Constants are Immutable
@@ -44,13 +44,13 @@ Constants can't be changed and assigned new values. They are part of the package
 inherently immutable.
 
 ```move
-module book::immutable_constants {
-    const ITEM_PRICE: u64 = 100;
+module book::immutable_constants;
 
-    // emits an error
-    fun change_price() {
-        ITEM_PRICE = 200;
-    }
+const ITEM_PRICE: u64 = 100;
+
+// emits an error
+fun change_price() {
+    ITEM_PRICE = 200;
 }
 ```
 
@@ -61,7 +61,7 @@ codebase. But due to constants being private to the module, they can't be access
 modules. One way to solve this is to define a "config" module that exports the constants.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/constants.move:config}}
+{{#include ../../../packages/samples/sources/move-basics/constants-config.move:config}}
 ```
 
 This way other modules can import and read the constants, and the update process is simplified. If

book/src/move-basics/function.md

@@ -7,7 +7,7 @@ the `fun` keyword at the module level. Just like any other module member, by def
 and can only be accessed from within the module.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/function.move:math}}
+{{#include ../../../packages/samples/sources/move-basics/function_math.move:math}}
 ```
 
 In this example, we define a function `add` that takes two arguments of type `u64` and returns their
@@ -38,7 +38,7 @@ function called `add` in the `math` module in the `book` package, the path to it
 `book::math::add`, or, if the module is imported, `math::add`.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/function.move:use_math}}
+{{#include ../../../packages/samples/sources/move-basics/function_use.move:use_math}}
 ```
 
 ## Multiple return values

book/src/move-basics/importing-modules.md

@@ -38,7 +38,7 @@ Another module defined in the same package can import the first module using the
 
 ```move
 // File: sources/module_two.move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:module_two}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-two.move:module_two}}
 ```
 
 ## Importing Members
@@ -48,7 +48,7 @@ function or a single type from a module. The syntax is the same as for importing
 add the member name after the module path.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:members}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-members.move:members}}
 ```
 
 ## Grouping Imports
@@ -58,7 +58,7 @@ when you need to import multiple members from the same module. Move allows group
 same module and from the same package.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:grouped}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-grouped.move:grouped}}
 ```
 
 Single function imports are less common in Move, since the function names can overlap and cause
@@ -69,7 +69,7 @@ To import members and the module itself in the group import, you can use the `Se
 `Self` keyword refers to the module itself and can be used to import the module and its members.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:self}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-self.move:self}}
 ```
 
 ## Resolving Name Conflicts
@@ -81,7 +81,7 @@ in different packages. To resolve the conflict and avoid ambiguity, Move offers
 rename the imported member.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:conflict}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-conflict-resolution.move:conflict}}
 ```
 
 ## Adding an External Dependency
@@ -116,5 +116,5 @@ To import a module from another package, you use the `use` keyword followed by t
 module path consists of the package address (or alias) and the module name separated by `::`.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:external}}
+{{#include ../../../packages/samples/sources/move-basics/importing-modules-external.move:external}}
 ```

book/src/move-basics/module.md

@@ -18,17 +18,19 @@ learn how to define a module, how to declare its members and how to access them
 
 ## Module declaration
 
-Modules are declared using the `module` keyword followed by the package address, module name and the
-module body inside the curly braces `{}`. The module name should be in `snake_case` - all lowercase
-letters with underscores between words. Modules names must be unique in the package.
+Modules are declared using the `module` keyword followed by the package address, module name,
+semicolon, and the module body. The module name should be in `snake_case` - all lowercase letters
+with underscores between words. Modules names must be unique in the package.
 
 Usually, a single file in the `sources/` folder contains a single module. The file name should match
 the module name - for example, a `donut_shop` module should be stored in the `donut_shop.move` file.
 You can read more about coding conventions in the
 [Coding Conventions](../special-topics/coding-conventions.md) section.
 
+> If you need to declare more than one module in a file, you must use [Module Block](#module-block).
+
 ```Move
-{{#include ../../../packages/samples/sources/move-basics/module.move:module}}
+{{#include ../../../packages/samples/sources/move-basics/module-label.move:module}}
 ```
 
 Structs, functions, constants and imports all part of the module:
@@ -63,6 +65,16 @@ book = "0x0"
 Module members are declared inside the module body. To illustrate that, let's define a simple module
 with a struct, a function and a constant:
 
+```Move
+{{#include ../../../packages/samples/sources/move-basics/module-members.move:members}}
+```
+
+## Module block
+
+Pre-2024 edition of Move required _module block_ - the contents of the module need to be surrounded
+by curly braces `{}`. The main reason to use block and not _label_ is if you need to define more
+than one module in a file.
+
 ```Move
 {{#include ../../../packages/samples/sources/move-basics/module.move:members}}
 ```

book/src/move-basics/ownership-and-scope.md

@@ -20,21 +20,21 @@ scope and executes every expression and statement. Once the function scope end,
 defined in it are dropped or deallocated.
 
 ```move
-module book::ownership {
-    public fun owner() {
-        let a = 1; // a is owned by the `owner` function
-    } // a is dropped here
-
-    public fun other() {
-        let b = 2; // b is owned by the `other` function
-    } // b is dropped here
-
-    #[test]
-    fun test_owner() {
-        owner();
-        other();
-        // a & b is not valid here
-    }
+module book::ownership;
+
+public fun owner() {
+    let a = 1; // a is owned by the `owner` function
+} // a is dropped here
+
+public fun other() {
+    let b = 2; // b is owned by the `other` function
+} // b is dropped here
+
+#[test]
+fun test_owner() {
+    owner();
+    other();
+    // a & b is not valid here
 }
 ```
 
@@ -48,18 +48,18 @@ If we changed the `owner` function to return the variable `a`, then the ownershi
 transferred to the caller of the function.
 
 ```move
-module book::ownership {
-    public fun owner(): u8 {
-        let a = 1; // a defined here
-        a // scope ends, a is returned
-    }
-
-    #[test]
-    fun test_owner() {
-        let a = owner();
-        // a is valid here
-    } // a is dropped here
+module book::ownership;
+
+public fun owner(): u8 {
+    let a = 1; // a defined here
+    a // scope ends, a is returned
 }
+
+#[test]
+fun test_owner() {
+    let a = owner();
+    // a is valid here
+} // a is dropped here
 ```
 
 ## Passing by Value
@@ -69,22 +69,22 @@ transferred to this function. When performing this operation, we _move_ the valu
 another. This is also called _move semantics_.
 
 ```move
-module book::ownership {
-    public fun owner(): u8 {
-        let a = 10;
-        a
-    } // a is returned
-
-    public fun take_ownership(v: u8) {
-        // v is owned by `take_ownership`
-    } // v is dropped here
-
-    #[test]
-    fun test_owner() {
-        let a = owner();
-        take_ownership(a);
-        // a is not valid here
-    }
+module book::ownership;
+
+public fun owner(): u8 {
+    let a = 10;
+    a
+} // a is returned
+
+public fun take_ownership(v: u8) {
+    // v is owned by `take_ownership`
+} // v is dropped here
+
+#[test]
+fun test_owner() {
+    let a = owner();
+    take_ownership(a);
+    // a is not valid here
 }
 ```
 
@@ -95,34 +95,34 @@ sequence of statements and expressions, and it has its own scope. Variables defi
 owned by this block, and when the block ends, the variables are dropped.
 
 ```move
-module book::ownership {
-    public fun owner() {
-        let a = 1; // a is owned by the `owner` function's scope
+module book::ownership;
+
+public fun owner() {
+    let a = 1; // a is owned by the `owner` function's scope
+    {
+        let b = 2; // b is owned by the block
         {
-            let b = 2; // b is owned by the block
-            {
-                let c = 3; // c is owned by the block
-            }; // c is dropped here
-        }; // b is dropped here
-        // a = b; // error: b is not valid here
-        // a = c; // error: c is not valid here
-    } // a is dropped here
-}
+            let c = 3; // c is owned by the block
+        }; // c is dropped here
+    }; // b is dropped here
+    // a = b; // error: b is not valid here
+    // a = c; // error: c is not valid here
+} // a is dropped here
 ```
 
 However, shall we use the return value of a block, the ownership of the variable is transferred to
 the caller of the block.
 
 ```move
-module book::ownership {
-    public fun owner(): u8 {
-        let a = 1; // a is owned by the `owner` function's scope
-        let b = {
-            let c = 2; // c is owned by the block
-            c // c is returned
-        }; // c is dropped here
-        a + b // both a and b are valid here
-    }
+module book::ownership;
+
+public fun owner(): u8 {
+    let a = 1; // a is owned by the `owner` function's scope
+    let b = {
+        let c = 2; // c is owned by the block
+        c // c is returned
+    }; // c is dropped here
+    a + b // both a and b are valid here
 }
 ```
 

book/src/move-basics/references.md

@@ -42,7 +42,6 @@ module book::metro_pass {
 {{#include ../../../packages/samples/sources/move-basics/references.move:header}}
 
 {{#include ../../../packages/samples/sources/move-basics/references.move:new}}
-}
 ```
 
 <!-- In [the previous section](./ownership-and-scope.md) we explained the ownership and scope in Move. We showed how the value is *moved* to a new scope, and how it changes the owner. In this section, we will explain how to *borrow* a reference to a value to avoid moving it, and how Move's *borrow checker* ensures that the references are used correctly. -->

book/src/move-basics/struct-methods.md

@@ -41,7 +41,7 @@ with `hero_` and `villain_` respectively. However, we can create aliases for the
 they can be called on the instances of the structs without the prefix.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/struct-methods.move:hero_and_villain}}
+{{#include ../../../packages/samples/sources/move-basics/struct-methods-2.move:hero_and_villain}}
 ```
 
 As you can see, in the test function, we called the `health` method on the instances of `Hero` and
@@ -57,7 +57,7 @@ associate it with the `Hero` struct. It will allow serializing the `Hero` struct
 bytes.
 
 ```move
-{{#include ../../../packages/samples/sources/move-basics/struct-methods.move:hero_to_bytes}}
+{{#include ../../../packages/samples/sources/move-basics/struct-methods-3.move:hero_to_bytes}}
 ```
 
 ## Further reading