deploy: a28dc1c

highlight.js

@@ -441,7 +441,7 @@ hljs.registerLanguage('move', function(hljs) {
         // module definition
         scope: 'module',
         begin: /\bmodule\b/,
-        end: /\{/,
+        end: /[;{]/,
         keywords: 'module',
         contains: [
           BLOCK_COMMENT,

move-basics/comments.html

@@ -201,25 +201,58 @@ <h1 id="comments"><a class="header" href="#comments">Comments</a></h1>
 documentation. There are three types of comments in Move: line comment, block comment, and doc
 comment.</p>
 <h2 id="line-comment"><a class="header" href="#line-comment">Line comment</a></h2>
-<pre><code class="language-Move">{{#include ../../../packages/samples/sources/move-basics/comments.move:line}}
-</code></pre>
 <p>You can use double slash <code>//</code> to comment out the rest of the line. Everything after <code>//</code> will be
 ignored by the compiler.</p>
-<pre><code class="language-Move">{{#include ../../../packages/samples/sources/move-basics/comments.move:line_2}}
+<pre><code class="language-Move">module book::comments_line;
+
+// let's add a note to everything!
+fun some_function_with_numbers() {
+    let a = 10;
+    // let b = 10 this line is commented and won't be executed
+    let b = 5; // here comment is placed after code
+    a + b; // result is 15, not 10!
+}
 </code></pre>
 <h2 id="block-comment"><a class="header" href="#block-comment">Block comment</a></h2>
 <p>Block comments are used to comment out a block of code. They start with <code>/*</code> and end with <code>*/</code>.
 Everything between <code>/*</code> and <code>*/</code> will be ignored by the compiler. You can use block comments to
 comment out a single line or multiple lines. You can even use them to comment out a part of a line.</p>
-<pre><code class="language-Move">{{#include ../../../packages/samples/sources/move-basics/comments.move:block}}
+<pre><code class="language-Move">module book::comments_block;
+
+fun /* you can comment everywhere */ go_wild() {
+    /* here
+        there
+        everywhere */ let a = 10;
+    let b = /* even here */ 10; /* and again */
+    a + b;
+}
+/* you can use it to remove certain expressions or definitions
+fun empty_commented_out() {
+
+}
+*/
 </code></pre>
 <p>This example is a bit extreme, but it shows how you can use block comments to comment out a part of
 a line.</p>
 <h2 id="doc-comment"><a class="header" href="#doc-comment">Doc comment</a></h2>
 <p>Documentation comments are special comments that are used to generate documentation for your code.
 They are similar to block comments, but they start with three slashes <code>///</code> and are placed before
 the definition of the item they document.</p>
-<pre><code class="language-Move">{{#include ../../../packages/samples/sources/move-basics/comments.move:doc}}
+<pre><code class="language-Move">/// Module has documentation!
+module book::comments_doc;
+
+/// This is a 0x0 address constant!
+const AN_ADDRESS: address = @0x0;
+
+/// This is a struct!
+public struct AStruct {
+    /// This is a field of a struct!
+    a_field: u8,
+}
+
+/// This function does something!
+/// And it's documented!
+fun do_something() {}
 </code></pre>
 <!-- TODO: docgen, which members are in the documentation -->
 

move-basics/constants.html

@@ -205,32 +205,66 @@ <h1 id="constants"><a class="header" href="#constants">Constants</a></h1>
 give names to static values that are used throughout a module. For example, if there's a default
 price for a product, you might define a constant for it. Constants are stored in the module's
 bytecode, and each time they are used, the value is copied.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::shop_price;
+
+use sui::{coin::Coin, sui::SUI};
+
+/// The price of an item in the shop.
+const ITEM_PRICE: u64 = 100;
+/// The owner of the shop, an address.
+const SHOP_OWNER: address = @0xa11ce;
+
+/// An item sold in the shop.
+public struct Item {}
+
+/// Purchase an item from the shop.
+public fun purchase(coin: Coin&lt;SUI&gt;): Item {
+    assert!(coin.value() == ITEM_PRICE, 0);
+
+    transfer::public_transfer(coin, SHOP_OWNER);
+
+    Item {}
+}
 </code></pre>
 <h2 id="naming-convention"><a class="header" href="#naming-convention">Naming Convention</a></h2>
 <p>Constants must start with a capital letter - this is enforced at the compiler level. For constants
 used as a value, there's a convention to use uppercase letters and underscores to separate words.
 It's a way to make constants stand out from other identifiers in the code. One exception is made for
 <a href="./assert-and-abort.html#assert-and-abort">error constants</a>, which are written in ECamelCase.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">/// Price of the item used at the shop.
+const ITEM_PRICE: u64 = 100;
+
+/// Error constant.
+const EItemNotFound: u64 = 1;
 </code></pre>
 <h2 id="constants-are-immutable"><a class="header" href="#constants-are-immutable">Constants are Immutable</a></h2>
 <p>Constants can't be changed and assigned new values. They are part of the package bytecode, and
 inherently immutable.</p>
-<pre><code class="language-move">module book::immutable_constants {
-    const ITEM_PRICE: u64 = 100;
+<pre><code class="language-move">module book::immutable_constants;
+
+const ITEM_PRICE: u64 = 100;
 
-    // emits an error
-    fun change_price() {
-        ITEM_PRICE = 200;
-    }
+// emits an error
+fun change_price() {
+    ITEM_PRICE = 200;
 }
 </code></pre>
 <h2 id="using-config-pattern"><a class="header" href="#using-config-pattern">Using Config Pattern</a></h2>
 <p>A common use case for an application is to define a set of constants that are used throughout the
 codebase. But due to constants being private to the module, they can't be accessed from other
 modules. One way to solve this is to define a &quot;config&quot; module that exports the constants.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::config;
+
+const ITEM_PRICE: u64 = 100;
+const TAX_RATE: u64 = 10;
+const SHIPPING_COST: u64 = 5;
+
+/// Returns the price of an item.
+public fun item_price(): u64 { ITEM_PRICE }
+/// Returns the tax rate.
+public fun tax_rate(): u64 { TAX_RATE }
+/// Returns the shipping cost.
+public fun shipping_cost(): u64 { SHIPPING_COST }
 </code></pre>
 <p>This way other modules can import and read the constants, and the update process is simplified. If
 the constants need to be changed, only the config module needs to be updated during the package

move-basics/function.html

@@ -189,20 +189,7 @@ <h1 id="function"><a class="header" href="#function">Function</a></h1>
 code into reusable units. Functions can take arguments and return a value. They are declared with
 the <code>fun</code> keyword at the module level. Just like any other module member, by default they're private
 and can only be accessed from within the module.</p>
-<pre><code class="language-move">module book::math;
-
-/// Function takes two arguments of type `u64` and returns their sum.
-/// The `public` visibility modifier makes the function accessible from
-/// outside the module.
-public fun add(a: u64, b: u64): u64 {
-    a + b
-}
-
-#[test]
-fun test_add() {
-    let sum = add(1, 2);
-    assert!(sum == 3, 0);
-}
+<pre><code class="language-move">{{#include ../../../packages/samples/sources/move-basics/function_math.move:math}}
 </code></pre>
 <p>In this example, we define a function <code>add</code> that takes two arguments of type <code>u64</code> and returns their
 sum. The function is called from the <code>test_add</code> function, which is a test function located in the
@@ -227,7 +214,14 @@ <h2 id="accessing-functions"><a class="header" href="#accessing-functions">Acces
 consists of the module path and the function name separated by <code>::</code>. For example, if you have a
 function called <code>add</code> in the <code>math</code> module in the <code>book</code> package, the path to it will be
 <code>book::math::add</code>, or, if the module is imported, <code>math::add</code>.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::use_math;
+
+use book::math;
+
+fun call_add() {
+    // function is called via the path
+    let sum = math::add(1, 2);
+}
 </code></pre>
 <h2 id="multiple-return-values"><a class="header" href="#multiple-return-values">Multiple return values</a></h2>
 <p>Move functions can return multiple values, which is useful when you need to return more than one

move-basics/importing-modules.html

@@ -219,34 +219,66 @@ <h2 id="importing-a-module"><a class="header" href="#importing-a-module">Importi
 </code></pre>
 <p>Another module defined in the same package can import the first module using the <code>use</code> keyword.</p>
 <pre><code class="language-move">// File: sources/module_two.move
+module book::module_two;
 
+use book::module_one; // importing module_one from the same package
+
+/// Calls the `new` function from the `module_one` module.
+public fun create_and_ignore() {
+    let _ = module_one::new();
+}
 </code></pre>
 <h2 id="importing-members"><a class="header" href="#importing-members">Importing Members</a></h2>
 <p>You can also import specific members from a module. This is useful when you only need a single
 function or a single type from a module. The syntax is the same as for importing a module, but you
 add the member name after the module path.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">{{#include ../../../packages/samples/sources/move-basics/importing-modules-members.move:members}}
 </code></pre>
 <h2 id="grouping-imports"><a class="header" href="#grouping-imports">Grouping Imports</a></h2>
 <p>Imports can be grouped into a single <code>use</code> statement using the curly braces <code>{}</code>. This is useful
 when you need to import multiple members from the same module. Move allows grouping imports from the
 same module and from the same package.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::grouped_imports;
+
+// imports the `new` function and the `Character` struct from
+// the `module_one` module
+use book::module_one::{new, Character};
+
+/// Calls the `new` function from the `module_one` module.
+public fun create_character(): Character {
+    new()
+}
 </code></pre>
 <p>Single function imports are less common in Move, since the function names can overlap and cause
 confusion. A recommended practice is to import the entire module and use the module path to access
 the function. Types have unique names and should be imported individually.</p>
 <p>To import members and the module itself in the group import, you can use the <code>Self</code> keyword. The
 <code>Self</code> keyword refers to the module itself and can be used to import the module and its members.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::self_imports;
+
+// imports the `Character` struct, and the `module_one` module
+use book::module_one::{Self, Character};
+
+/// Calls the `new` function from the `module_one` module.
+public fun create_character(): Character {
+    module_one::new()
+}
 </code></pre>
 <h2 id="resolving-name-conflicts"><a class="header" href="#resolving-name-conflicts">Resolving Name Conflicts</a></h2>
 <p>When importing multiple members from different modules, it is possible to have name conflicts. For
 example, if you import two modules that both have a function with the same name, you will need to
 use the module path to access the function. It is also possible to have modules with the same name
 in different packages. To resolve the conflict and avoid ambiguity, Move offers the <code>as</code> keyword to
 rename the imported member.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::conflict_resolution;
+
+// `as` can be placed after any import, including group imports
+use book::module_one::{Self as mod, Character as Char};
+
+/// Calls the `new` function from the `module_one` module.
+public fun create(): Char {
+    mod::new()
+}
 </code></pre>
 <h2 id="adding-an-external-dependency"><a class="header" href="#adding-an-external-dependency">Adding an External Dependency</a></h2>
 <p>Every new package generated via the <code>sui</code> binary features a <code>Move.toml</code> file with a single
@@ -270,7 +302,10 @@ <h2 id="importing-a-module-from-another-package"><a class="header" href="#import
 Standard Library package and can be used to access the standard library modules.</p>
 <p>To import a module from another package, you use the <code>use</code> keyword followed by the module path. The
 module path consists of the package address (or alias) and the module name separated by <code>::</code>.</p>
-<pre><code class="language-move">
+<pre><code class="language-move">module book::imports;
+
+use std::string; // std = 0x1, string is a module in the standard library
+use sui::coin;   // sui = 0x2, coin is a module in the Sui Framework
 </code></pre>
 
                     </main>

move-basics/module.html

@@ -199,14 +199,20 @@ <h1 id="module"><a class="header" href="#module">Module</a></h1>
 and all of the members of the module are private to the module by default. In this section you will
 learn how to define a module, how to declare its members and how to access them from other modules.</p>
 <h2 id="module-declaration"><a class="header" href="#module-declaration">Module declaration</a></h2>
-<p>Modules are declared using the <code>module</code> keyword followed by the package address, module name and the
-module body inside the curly braces <code>{}</code>. The module name should be in <code>snake_case</code> - all lowercase
-letters with underscores between words. Modules names must be unique in the package.</p>
+<p>Modules are declared using the <code>module</code> keyword followed by the package address, module name,
+semicolon, and the module body. The module name should be in <code>snake_case</code> - all lowercase letters
+with underscores between words. Modules names must be unique in the package.</p>
 <p>Usually, a single file in the <code>sources/</code> folder contains a single module. The file name should match
 the module name - for example, a <code>donut_shop</code> module should be stored in the <code>donut_shop.move</code> file.
 You can read more about coding conventions in the
 <a href="../special-topics/coding-conventions.html">Coding Conventions</a> section.</p>
-<pre><code class="language-Move">
+<blockquote>
+<p>If you need to declare more than one module in a file, you must use <a href="#module-block">Module Block</a>.</p>
+</blockquote>
+<pre><code class="language-Move">// Module label.
+module book::my_module;
+
+// module body
 </code></pre>
 <p>Structs, functions, constants and imports all part of the module:</p>
 <ul>
@@ -232,6 +238,27 @@ <h2 id="address--named-address"><a class="header" href="#address--named-address"
 <h2 id="module-members"><a class="header" href="#module-members">Module members</a></h2>
 <p>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:</p>
+<pre><code class="language-Move">module book::my_module_with_members;
+
+// import
+use book::my_module;
+
+// a constant
+const CONST: u8 = 0;
+
+// a struct
+public struct Struct {}
+
+// method alias
+public use fun function as Struct.struct_fun;
+
+// function
+fun function(_: &amp;Struct) { /* function body */ }
+</code></pre>
+<h2 id="module-block"><a class="header" href="#module-block">Module block</a></h2>
+<p>Pre-2024 edition of Move required <em>module block</em> - the contents of the module need to be surrounded
+by curly braces <code>{}</code>. The main reason to use block and not <em>label</em> is if you need to define more
+than one module in a file.</p>
 <pre><code class="language-Move">module book::my_block_module_with_members {
     // import
     use book::my_module;