Fundamentals to Declarations [Draft]

doc/md/fundamentals/basic-syntax/assertion.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 14
+---
+# Assertions
+
+An assertion checks a condition at runtime and traps if it fails.
+
+```motoko
+let n = 10;
+assert n % 2 == 1; // Traps
+```
+
+```motoko
+let n = 10;
+assert n % 2 == 0; // Succeeds
+```
+
+Assertions help catch logic errors early, but should not be used for regular error handling.
+
+<!---
+
+Insert link to regular error handling doc when available
+
+Insert link to base library reference for Assertions
+-->

doc/md/fundamentals/basic-syntax/characters.md

@@ -1,5 +1,22 @@
 ---
-sidebar_position: 3
+sidebar_position: 6
 ---
 
-# Characters
+# Characters
+
+The `Char` type in Motoko represents a single unicode character (`'`) delimited.
+
+```motoko
+let letter: Char = 'A';
+let symbol: Char = '☃';
+```
+
+Comparing characters
+
+```motoko
+'I' == 'i' //false
+```
+
+## Quick references
+
+- [Base library Char](https://internetcomputer.org/docs/current/motoko/main/base/Char)

doc/md/fundamentals/basic-syntax/comments.md

@@ -1,5 +1,43 @@
 ---
-sidebar_position: 7
+sidebar_position: 10
 ---
 
-# Comments
+# Comments  
+
+Motoko supports single-line, multi-line, and nested comments:
+
+Use `//` for comments that extend to the end of a line.
+
+  ```motoko
+  // This is a single-line comment
+  ```
+
+Use `/* ... */` for block comments spanning multiple lines.
+
+  ```motoko
+  /* This is a
+     multi-line comment */
+  ```
+
+Multi-line comments can be nested within each other.
+
+  ```motoko
+  /* Outer comment
+     /* Nested comment */
+     End of outer comment */
+  ```
+
+Use `///` for function or module documentation.
+
+  ```motoko
+  /// Returns the sum of two integers.
+  func add(a: Int, b: Int): Int {
+    a + b
+  }
+  ```
+
+## Quick references
+
+- [Comment style guide](https://internetcomputer.org/docs/current/motoko/main/reference/style/#comments)
+
+- [Generating Motoko documentation](https://internetcomputer.org/docs/current/motoko/main/reference/generating-docs)

doc/md/fundamentals/basic-syntax/defining_an_actor.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+# Defining an actor
+
+In Motoko, an actor is a unit of computation that encapsulates state and behavior. Unlike traditional functions or objects in other programming languages, actors operate independently and interact with each other through asynchronous messaging.
+
+A Motoko program typically starts by defining an actor. The example below declares an actor named `Main` with a `hello` function that returns a `"Hello, world!"` message:
+
+```motoko
+actor Main {
+  public query func hello() : async Text {
+    "Hello, world!"
+  };
+};
+
+await Main.hello();
+```
+
+A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. When Motoko code is compiled, this interface is automatically generated in **[Candid](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/candid/candid-concepts)**, an interface description language.
+
+Since actors in Motoko communicate asynchronously, `await` ensures the result is retrieved once the function completes.
+
+## Quick references
+
+- [Actors](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/actors-async)

doc/md/fundamentals/basic-syntax/floats.md

@@ -1,5 +1,16 @@
 ---
-sidebar_position: 2
+sidebar_position: 5
 ---
 
-# Floats
+# Floats
+
+Floating-point numbers in Motoko are represented using the `Float` type, which corresponds to a 64-bit double-precision floating-point number.
+
+```motoko
+let pi: Float = 3.14159;
+let exp: Float = 2.71828;
+```
+
+## Quick references
+
+- [Base library Float](https://internetcomputer.org/docs/current/motoko/main/base/Float)

doc/md/fundamentals/basic-syntax/identifiers.md

@@ -1,5 +1,11 @@
 ---
-sidebar_position: 9
+sidebar_position: 11
 ---
 
-# Identifiers
+# Identifiers
+
+Identifiers are names used for variables, functions, and other entities. They must start with a letter and can contain letters, digits, and underscores.
+
+```motoko
+let number = 10;
+```

doc/md/fundamentals/basic-syntax/imports.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+# Imports  
+
+Package imports should be at the top of the source file. Imports allow you to reuse code from external libraries or modules, making your code easier to maintain and manage. You can import from:
+
+1. Standard modules provided by the base library:
+
+```motoko
+import Text "mo:base/Text";
+```  
+
+2. Third-party packages installed via the Mops package manager:
+
+```motoko
+import Package "mo:packagename";
+```  
+
+3. Files within your own project:
+
+```motoko
+import Utils "utils";
+```  
+
+You can also import specific functions from a module:
+
+```motoko
+import { compare } "mo:base/Nat";
+```
+
+## Quick references
+
+- [Modules and imports](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/modules-and-imports/)

doc/md/fundamentals/basic-syntax/integers.md

@@ -1,5 +1,46 @@
 ---
-sidebar_position: 1
+sidebar_position: 4
 ---
 
-# Integers
+# Integers
+
+`Int` represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2).
+
+For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (`Int8`, `Int16`, `Int32`, `Int64`). These types can overflow if their limits are exceeded, resulting in a runtime error.
+
+```motoko
+let a: Int = -42;
+let b: Int = 0;
+let c: Int = 12345;
+```
+
+## Unbounded integers
+
+By default, `Int` is unbounded, meaning it can grow as large (or as small) as needed without causing overflow:
+
+```motoko
+let bigNumber: Int = 999_999_999_999_999;
+```
+
+## Bounded integers
+
+For scenarios requiring fixed-size integers, Motoko offers bounded integer types with specific bit-widths:
+
+- `Int8`  (8-bit signed integer)
+- `Int16` (16-bit signed integer)
+- `Int32` (32-bit signed integer)
+- `Int64` (64-bit signed integer)
+
+Bounded integers can overflow if their limits are exceeded, resulting in a runtime error:
+
+```motoko
+// let overflowInt: Int8 = 128; // Error: literal out of range Int8
+```
+
+## Quick references
+
+- [Base library Int](https://internetcomputer.org/docs/current/motoko/main/base/Int)
+- [Base library Int8](https://internetcomputer.org/docs/current/motoko/main/base/Int8)
+- [Base library Int16](https://internetcomputer.org/docs/current/motoko/main/base/Int16)
+- [Base library Int32](https://internetcomputer.org/docs/current/motoko/main/base/Int32)
+- [Base library Int64](https://internetcomputer.org/docs/current/motoko/main/base/Int64)

doc/md/fundamentals/basic-syntax/keywords.md

@@ -1,5 +1,18 @@
 ---
-sidebar_position: 8
+sidebar_position: 12
 ---
 
-# Keywords
+# Keywords
+
+Motoko reserves certain words for its syntax and they cannot be used as identifiers. These include:
+
+```motoko
+actor      and        assert     async      async*     await      await*
+break      case       catch      class      composite  continue   debug
+debug_show do         else       false      flexible   finally    for
+from_candid func      if         ignore     import     in         module
+not        null       persistent object     or         label      let
+loop       private    public     query      return     shared     stable
+switch     system     throw      to_candid  true       transient  try
+type       var        while      with
+```

doc/md/fundamentals/basic-syntax/literals.md

@@ -1,5 +1,24 @@
 ---
-sidebar_position: 5
+sidebar_position: 8
 ---
 
-# Literals
+# Literals
+
+Literals are fixed values written directly in the code.
+
+- Integer literals: `42`, `0x2A` (hexadecimal)
+- Float literals: `3.14`, `2.5e3`
+- Character literals: `'A'`, `'☃'`
+- Text literals: `"Hello"`
+
+You can use literals directly in expressions:
+
+Numeric literal in expression
+
+```motoko
+100 + 50
+```
+
+## Quick references
+
+- [Literals](https://internetcomputer.org/docs/current/motoko/main/reference/language-manual/#literals)

doc/md/fundamentals/basic-syntax/printing_values.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 3
+---
+# Printing values
+
+Motoko uses `Debug.print` to output text to the terminal. It takes a `Text` value and returns `()`, meaning it has no meaningful return value.  
+
+```motoko
+import Debug "mo:base/Debug";
+Debug.print("Hello, world!");
+```
+
+For debugging, `debug_show` converts most Motoko values into `Text`. The function handles primitive types and simple collections well but may not work with nested, recursive, or complex custom types, which may require **transformation or unwrapping** before use.
+
+```motoko
+import Debug "mo:base/Debug";
+Debug.print(debug_show(42)); // "42"
+```
+
+Since printing modifies output, it is considered an **impure function**, unlike pure functions that return values without side effects.
+
+`debug_show(42)` is pure because it always returns `"42"` without affecting anything outside the function.
+
+`Debug.print`("Hello, World!") is impure because it causes a side effect by printing to the console.
+
+## Quick references
+
+- [Base library Debug](https://internetcomputer.org/docs/current/motoko/main/base/Debug)

doc/md/fundamentals/basic-syntax/text.md

@@ -1,5 +1,21 @@
 ---
-sidebar_position: 4
+sidebar_position: 7
 ---
 
-# Text
+# Text
+
+Sequences of characters are handled using the `Text` type, which represents immutable strings of unicode characters (`"`) delimited.
+
+```motoko
+let greeting: Text = "Hello, world!";
+```
+
+Concatenating text
+
+```motoko
+"ICP" # "x" # "Motoko" //ICP x Motoko
+```
+
+## Quick references
+
+- [Base library Text](https://internetcomputer.org/docs/current/motoko/main/base/Text)

doc/md/fundamentals/basic-syntax/traps.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 13
+---
+# Traps
+
+A trap is a runtime error that causes execution to abort immediately. Common causes include division by zero, out-of-bounds array access and pattern match failure
+
+If a trap occurs inside an actor message, only that message fails—other messages continue execution.  
+
+To trigger a trap manually, use `Debug.trap`:  
+
+```motoko
+import Debug "mo:base/Debug";
+
+Debug.trap("oops!");
+```
+
+## Quick references
+
+-[Traps](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/actors-async/#traps)