Reorganize Sway docs and compress some sections

docs/src/SUMMARY.md

@@ -15,39 +15,40 @@
 - [SDK](./sdks/index.md)
   - [Rust SDK](./sdks/rust-sdk.md)
   - [TypeScript SDK](./sdks/typescript-sdk.md)
-- [Basics](./basics/index.md)
-  - [Overview](./basics/overview.md)
+- [Program Types](./sway-program-types/index.md)
+  - [Contracts](./sway-program-types/smart_contracts.md)
+  - [Libraries](./sway-program-types/libraries.md)
+  - [Scripts](./sway-program-types/scripts.md)
+  - [Predicates](./sway-program-types/predicates.md)
+- [Sway Language Basics](./basics/index.md)
+
   - [Variables](./basics/variables.md)
   - [Built-in Types](./basics/built_in_types.md)
-  - [Custom Types](./basics/custom_types.md)
+  - [Blockchain Types](./basics/blockchain_types.md)
   - [Functions](./basics/functions.md)
-  <!-- - [Reference Types](./basics/reference_types.md) -->
-- [Control Flow](./control-flow/index.md)
-  - [Loops](./control-flow/loops.md)
+  - [Structs and Tuples](./basics/structs_and_tuples.md)
+  - [Methods and Associated Functions](./basics/methods_and_associated_functions.md)
+  - [Comments and Logging](./basics/comments_and_logging.md)
+  - [Control Flow](./basics/control_flow.md)
+  - [Reference Types](./basics/reference_types.md)
+
+- [Blockchain Development with Sway](./blockchain-development/index.md)
+  - [Contract Storage](./blockchain-development/storage.md)
+  - [Function Purity](./blockchain-development/purity.md)
+  - [Identifiers](./blockchain-development/identifiers.md)
+  - [Native Assets](./blockchain-development/native_assets.md)
 - [Testing](./testing/index.md)
+
   - [Testing with Rust](./testing/testing-with-rust.md)
   - [Testing with TypeScript](./testing/testing-with-typescript.md)
-- [Sway on the Chain](./sway-on-chain/index.md)
-  - [Program Types](./sway-on-chain/program_types.md)
-  - [Contracts](./sway-on-chain/smart_contracts.md)
-  - [Libraries](./sway-on-chain/libraries.md)
-  - [Scripts](./sway-on-chain/scripts.md)
-  - [Predicates](./sway-on-chain/predicates.md)
-- [Smart Contract Development](./smart-contract-development/index.md)
-  - [Contract Storage](./smart-contract-development/storage.md)
-  - [Function Purity](./smart-contract-development/purity.md)
+
 - [Advanced Concepts](./advanced/index.md)
   - [Generic Types](./advanced/generic_types.md)
   - [Traits](./advanced/traits.md)
   - [Trait Constraints](./advanced/trait_constraints.md)
   - [Assembly](./advanced/assembly.md)
-- [Blockchain Concepts](./blockchain-concepts/index.md)
-  - [Blockchain Types](./blockchain-concepts/blockchain_types.md)
-  - [Identifiers](./blockchain-concepts/identifiers.md)
-  - [Native Assets](./blockchain-concepts/native_assets.md)
-- [Conventions](./style/index.md)
-  - [Capitalization](./style/capitalization.md)
 - [Reference](./reference/index.md)
+  - [Style Guide](./reference/style_guide.md)
   - [Temporary Workarounds](./reference/temporary_workarounds.md)
   - [Differences From Solidity](./reference/solidity_differences.md)
   - [Differences From Rust](./reference/rust_differences.md)

docs/src/blockchain-concepts/blockchain_types.md → docs/src/basics/blockchain_types.md

@@ -1,6 +1,8 @@
 # Blockchain Types
 
-Sway has a selection of types provided via the standard library ([`lib-std`](https://github.com/FuelLabs/sway-lib-std)) which both add a degree of type-safety, as well as make the intention of the developer more clear.
+Sway is fundamentally a blockchain language, and it offers a selection of types tailored for the blockchain use case.
+
+These are provided via the standard library ([`lib-std`](https://github.com/FuelLabs/sway-lib-std)) which both add a degree of type-safety, as well as make the intention of the developer more clear.
 
 ## `Address` Type
 

docs/src/basics/comments_and_logging.md

@@ -0,0 +1,37 @@
+# Comments and Logging
+
+## Comments
+
+Comments in Sway start with two slashes and continue until the end of the line. For comments that extend beyond a single line, you'll need to include `//` on each line.
+
+```sway
+// hello world
+```
+
+```sway
+// let's make a couple of lines
+// commented.
+```
+
+You can also place comments at the ends of lines containing code.
+
+```sway
+fn main() {
+    let baz = 8; // Eight is a lucky number
+}
+```
+
+## Logging
+
+To log integers, you can use the `log_u64`, `log_u32`, `log_u16`, or `log_u8` functions from the `lib-std` library.
+
+```sway
+use std::chain::log_u64;
+
+fn main() {
+    let baz = 8;
+    log_u64(baz);
+}
+```
+
+Note that you cannot log arbitrary structs yet because we do not yet support serialization.

docs/src/basics/control_flow.md

@@ -0,0 +1,85 @@
+# Control Flow
+
+## `if` expressions
+
+Sway supports _if_, _else_, and _else if_ expressions that allow you to branch your code depending on conditions.
+
+For example:
+
+```sway
+fn main() {
+    let number = 6;
+
+    if number % 4 == 0 {
+        // do something
+    } else if number % 3 == 0 {
+        // do something else
+    } else {
+        // do something else
+    }; // <------------ note this semicolon
+}
+```
+
+In Sway, note that a _statement_ is a _declaration **or** expression with a semicolon after it_. This means that you need to add a semicolon after an `if` to turn it into a statement, if it is being used for control flow.
+
+This need for a semicolon after if expressions to turn them into statements will be removed eventually, but it hasn't been removed yet.
+
+### Using `if` in a `let` statement
+
+Like Rust, `if`s are expressions in Sway. What this means is you can use `if` expressions on the right side of a `let` statement to assign the outcome to a variable.
+
+```sway
+let my_data = if some_bool < 10 { foo() } else { bar() };
+```
+
+Note that all branches of the `if` expression must return a value of the same type or the code will panic.
+
+## Loops
+
+### `while`
+
+Loops in Sway are currently limited to `while` loops. This is what they look like:
+
+```sway
+while counter < 10 {
+    counter = counter + 1;
+}
+```
+
+You need the `while` keyword, some condition (`value < 10` in this case) which will be evaluated each iteration, and a block of code inside the curly braces (`{...}`) to execute each iteration.
+
+### `break` and `continue`
+
+There are no `break` or `continue` keywords yet, but [they're coming](https://github.com/FuelLabs/sway/issues/587).
+
+For now, the way to break out of a `while` loop early is to manually invalidate the condition. In this case, that just means setting `counter` to be >= 10.
+
+Building on the previous example, here's what that might look like:
+
+```sway
+let mut counter = 0;
+let mut break_early = false;
+while counter < 10 {
+    if break_early == true {
+        // here we ensure the condition will evaluate to false, breaking the loop
+        counter = 10
+    } else {
+        // calling some other function to set the bool value
+        break_early = get_bool_value();
+        counter = counter + 1;
+    };
+}
+```
+
+### Nested loops
+
+You can also use nested `while` loops if needed:
+
+```sway
+while condition_1 == true {
+    // do stuff...
+    while condition_2 == true {
+        // do more stuff...
+    }
+}
+```

docs/src/basics/functions.md

@@ -8,7 +8,9 @@ fn equals(first_param: u64, second_param: u64) -> bool {
 }
 ```
 
-We have just declared a function named `equals` which takes two parameters: `first_param` and `second_param`. This function also returns a `bool` value, i.e. either `true` or `false`. This function returns `true` if the two given parameters are equal, and `false` if they are not. If we want to use this function, we can do so like this:
+We have just declared a function named `equals` which takes two parameters: `first_param` and `second_param`. The parameters must both be 64-bit unsigned integers.
+
+This function also returns a `bool` value, i.e. either `true` or `false`. This function returns `true` if the two given parameters are equal, and `false` if they are not. If we want to use this function, we can do so like this:
 
 ```sway
 fn main() {

docs/src/basics/index.md

@@ -1,11 +1,15 @@
-# Basics
+# Sway Language basics
+
+Sway is a programming language designed for the FuelVM. It is a statically typed, compiled language with type inference and traits. Sway aims to make smart contract development safer and more performant through the use of strong static analysis and compiler feedback.
 
 Sway basics.
 
-- [Overview](./overview.md)
 - [Variables](./variables.md)
 - [Built-in Types](./built_in_types.md)
-- [Custom Types](./custom_types.md)
 - [Blockchain Types](./blockchain_types.md)
 - [Functions](./functions.md)
-<!-- - [Reference Types](./reference_types.md) -->
+- [Structs and Tuples](./structs_and_tuples.md)
+- [Methods and Associated Functions](./structs_and_tuples.md)
+- [Control Flow](./control-flow.md)
+- [Comments and Logging](./comments_and_logging.md)
+- [Reference Types](./reference_types.md)

docs/src/basics/methods_and_associated_functions.md

@@ -0,0 +1,65 @@
+# Methods and Associated Functions
+
+Methods are similar to functions in that we declare them with the `fn` keyword and they have parameters and return a value. However, unlike functions, _Methods_ are defined within the context of a struct (or enum), and either refers to that type or mutates it. The first parameter of a method is always `self`, which represents the instance of the struct the method is being called on.
+
+_Associated functions_ are very similar to _methods_, in that they are also defined in the context of a struct or enum, but they do not actually use any of the data in the struct and as a result do not take _self_ as a parameter. Associated functions could be standalone functions, but they are included in a specific type for organizational or semantic reasons.
+
+To declare methods and associated functions for a struct or enum, use an _impl block_. Here, `impl` stands for implementation.
+
+```sway
+script;
+
+struct Foo {
+    bar: u64,
+    baz: bool,
+}
+
+impl Foo {
+    // this is a _method_, as it takes `self` as a parameter.
+    fn is_baz_true(self) -> bool {
+        self.baz
+    }
+
+    // this is an _associated function_, since it does not take `self` as a parameter.
+    fn new_foo(number: u64, boolean: bool) -> Foo {
+        Foo {
+            bar: number,
+            baz: boolean,
+        }
+    }
+}
+
+fn main() {
+    let foo = ~Foo::new_foo(42, true);
+    assert(foo.is_baz_true());
+}
+```
+
+Note the syntax of the associated function call: `~Foo::new_foo(42, true);`. This bit of syntax is unique to Sway: when referring to a type directly, you preface the type with a tilde (`~`). To call an associated function, refer to the type and then the function name.
+To call a method, simply use dot syntax: `foo.iz_baz_true()`.
+
+## Syntax Examples
+
+```sway
+enum Color {
+    Blue   : (),
+    Green  : (),
+    Red    : (),
+    Silver : (),
+    Grey   : (),
+    // etc...
+}
+
+enum Make {
+    Ford      : (),
+    Toyota    : (),
+    Mazda     : (),
+    Chevrolet : (),
+    BMW       : (),
+    // etc...
+}
+struct Car {
+    make: CarMake,
+    color: Color,
+}
+```

docs/src/basics/custom_types.md → docs/src/basics/structs_and_tuples.md

@@ -1,4 +1,4 @@
-# Custom Types
+# Structs and Tuples
 
 ## Structs
 
@@ -120,68 +120,3 @@ let event = InventoryEvent::ItemLoss(Claim {
 _This information is not vital if you are new to the language, or programming in general._
 
 Enums do have some memory overhead. To know which variant is being represented, Sway stores a one-word (8-byte) tag for the enum variant. The space reserved after the tag is equivalent to the size of the _largest_ enum variant. So, to calculate the size of an enum in memory, add 8 bytes to the size of the largest variant. For example, in the case of `Color` above, where the variants are all `()`, the size would be 8 bytes since the size of the largest variant is 0 bytes.
-
-## Methods and Associated Functions
-
-_Methods_ are functions that are associated with a specific type and either refer to that type or mutate it. _Associated functions_ are very similar, but they do not use any of the data in the type. Associated functions could be standalone functions, but they
-are included in a specific type for organizational or semantic reasons.
-
-To declare methods and associated functions for a struct or enum, use an _impl block_. Here, `impl` stands for implementation.
-
-```sway
-script;
-
-struct Foo {
-    bar: u64,
-    baz: bool,
-}
-
-impl Foo {
-    // this is a _method_, as it takes `self` as a parameter.
-    fn is_baz_true(self) -> bool {
-        self.baz
-    }
-
-    // this is an _associated function_, since it does not take `self` as a parameter.
-    fn new_foo(number: u64, boolean: bool) -> Foo {
-      Foo {
-          bar: number,
-          baz: boolean,
-      }
-    }
-}
-
-fn main() {
-    let foo = ~Foo::new_foo(42, true);
-    assert(foo.is_baz_true());
-}
-```
-
-Note the syntax of the associated function call: `~Foo::new_foo(42, true);`. This bit of syntax is unique to Sway: when referring to a type directly, you preface the type with a tilde (`~`). To call an associated function, refer to the type and then the function name.
-To call a method, simply use dot syntax: `foo.iz_baz_true()`.
-
-## Syntax Examples
-
-```sway
-enum Color {
-    Blue   : (),
-    Green  : (),
-    Red    : (),
-    Silver : (),
-    Grey   : (),
-    // etc...
-}
-
-enum Make {
-    Ford      : (),
-    Toyota    : (),
-    Mazda     : (),
-    Chevrolet : (),
-    BMW       : (),
-    // etc...
-}
-struct Car {
-    make: CarMake,
-    color: Color,
-}
-```

docs/src/blockchain-development/index.md

@@ -0,0 +1,10 @@
+# Blockchain Development with Sway
+
+Sway is fundamentally a blockchain language. Because of this, it has some features and requirements that you may not have seen in general-purpose programming languages.
+
+These are also some concepts related to the FuelVM and Fuel ecosystem that you may utilize when writing Sway.
+
+- [Contract Storage](./storage.md)
+- [Function Purity](./purity.md)
+- [Identifiers](./identifiers.md)
+- [Native Assets](./native_assets.md)