From 253e4bbb48c29fb2781c9453f86bdaa3686296fe Mon Sep 17 00:00:00 2001
From: Araozu <fernando@araozu.dev>
Date: Thu, 16 May 2024 10:00:46 -0500
Subject: [PATCH] Add docs

---
 src/pages/learn/basics/comments.md           |   1 +
 src/pages/learn/basics/datatypes.md          |  35 ++++--
 src/pages/learn/basics/operators.md          | 114 ++++++++++++++++++-
 src/pages/learn/basics/variables.md          |   5 +
 src/pages/learn/data-structures/maps.md      |   2 +
 src/pages/learn/flow-control/blocks.md       |  16 ++-
 src/pages/learn/flow-control/conditionals.md |   2 +
 src/pages/learn/flow-control/loops.md        |   4 +-
 src/pages/learn/functions/declaration.md     |   2 +
 src/pages/learn/index.md                     |   3 +-
 10 files changed, 172 insertions(+), 12 deletions(-)

diff --git a/src/pages/learn/basics/comments.md b/src/pages/learn/basics/comments.md
index 7f7e9d3..e4cdb56 100644
--- a/src/pages/learn/basics/comments.md
+++ b/src/pages/learn/basics/comments.md
@@ -30,4 +30,5 @@ Only these two:
 */
 ```
 
+TBD: Doc comments use triple slash `///`? or `/** */`?
 
diff --git a/src/pages/learn/basics/datatypes.md b/src/pages/learn/basics/datatypes.md
index 25054fb..084c634 100644
--- a/src/pages/learn/basics/datatypes.md
+++ b/src/pages/learn/basics/datatypes.md
@@ -5,7 +5,10 @@ title: Datatypes
 
 # Datatypes
 
-Datatypes's first character are always uppercase.
+THP requires that all datatypes start their name with an
+uppercase letter.
+
+The following are basic datatypes.
 
 ## Int
 
@@ -13,8 +16,17 @@ Same as php int
 
 ```thp
 Int age = 32
+// Hexadecimal numbers start with 0x
 Int red = 0xff0000
+// Octal numbers start with 0o
+Int permissions = 0o775
+// Binary numbers start with 0b
 Int char_code = 0b01000110
+
+// IMPORTANT!
+// Since Octal starts with `0o`, using just a leading 0
+// will result in a decimal!
+Int not_octal = 032     // This is 32, not 26
 ```
 
 
@@ -25,26 +37,35 @@ Same as php float
 
 ```thp
 Float pi = 3.141592
+Float light = 2.99e+8
 ```
 
 
 ## String
 
-Same as php string
+THP strings use **only** double quotes. Single quotes are
+used elsewhere.
 
 ```thp
 String name = "Rose"
 ```
 
-
-## Bool
-
-Same as php bool
+Strings have interpolation with `{}`.
 
 ```thp
-Bool is_true = true
+print("Hello, {name}")      // Hello, Rose
 ```
 
 
+## Bool
 
+THP booleans are `true` and `false`. They are case sensitive,
+**only lowercase.**
 
+```thp
+Bool is_true = true
+Bool is_false = false
+
+// This is a compile error
+val invalid = TRUE
+```
diff --git a/src/pages/learn/basics/operators.md b/src/pages/learn/basics/operators.md
index d6a2813..925fad4 100644
--- a/src/pages/learn/basics/operators.md
+++ b/src/pages/learn/basics/operators.md
@@ -1,10 +1,120 @@
 ---
 layout: ../../../layouts/PagesLayout.astro
-title: Install
+title: Operators
 ---
 
 # Operators
 
-Some common operators
+
+Most of the PHP operators are present in THP.
+
+## Numbers
+
+```thp
+var number = 322
+
+number + 1
+number - 1
+number * 1
+number / 1
+number % 2
+
+number += 1
+number -= 1
+number *= 1
+number /= 1
+number %= 2
+```
+
+**There are no prefix/postfix increment**, use `+=` or `-=`.
+
+```thp
+// Use
+number += 1
+
+// instead of
+number++   // This is a compile error 
+```
+
+### Comparison
+
+These operators will not do implicit type conversion. They can
+only be used with same datatypes.
+
+```thp
+v1 < v2
+v1 <= v2
+v1 > v2
+v1 >= v2
+```
+
+There is only `==` and `!=`. They are equivalent to `===` and `!==`.
+
+```thp
+v1 == v2
+v1 != v2
+```
+
+
+### Bitwise
+
+TBD
+
+```thp
+number and 1
+number or 2
+number xor 1
+number xand 1
+```
+
+## Strings
+
+TBD.
+
+Strings **do not use `.`** for concatenation. They use `+`.
+
+```thp
+"Hello " + "world."
+```
+
+However, the plus operator `+` does not implicitly convert types.
+
+```thp
+"Hello " + 322      // This is an error
+```
+
+
+## Boolean
+
+These operators work **only with booleans**, they do not perform
+type coercion.
+
+```thp
+c1 && c2
+c1 || c2
+```
+
+## Ternary
+
+There is no ternary operator. See [Conditionals](/learn/flow-control/conditionals) for alternatives.
+
+
+## Null
+
+These are detailed in their section: [Nullable types](/learn/error-handling/null)
+
+```thp
+val person = some_fun()
+
+person?.name
+person?.name ?? "Jane"
+person?.greet?.()
+
+if person?
+{
+    person.name
+}
+```
+
 
 
diff --git a/src/pages/learn/basics/variables.md b/src/pages/learn/basics/variables.md
index 3666b2c..416a3f0 100644
--- a/src/pages/learn/basics/variables.md
+++ b/src/pages/learn/basics/variables.md
@@ -8,6 +8,11 @@ title: Variables
 
 thp distinguishes between mutable and immutable variables.
 
+Variables have to be declared in THP, to avoid issues with scopes.
+It is a compile error to use undeclared variables.
+
+Variable names **must** begin with a lowercase letter.
+
 ## Immutable variables
 
 Defined with `val`, followed by a variable name and a value.
diff --git a/src/pages/learn/data-structures/maps.md b/src/pages/learn/data-structures/maps.md
index 268adcd..c8249f2 100644
--- a/src/pages/learn/data-structures/maps.md
+++ b/src/pages/learn/data-structures/maps.md
@@ -5,6 +5,8 @@ title: Maps
 
 # Maps
 
+TBD.
+
 Also known as Associative Arrays, or Objects in other languages.
 
 All maps must have a definition, which define their fields and datatypes.
diff --git a/src/pages/learn/flow-control/blocks.md b/src/pages/learn/flow-control/blocks.md
index 5e95d1c..21afdee 100644
--- a/src/pages/learn/flow-control/blocks.md
+++ b/src/pages/learn/flow-control/blocks.md
@@ -5,5 +5,19 @@ title: Blocks
 
 # Blocks
 
-Blocks :D
+Blocks of code are denoted with brackets `{}`.
+
+Blocks can be assigned to variables, in which case
+they are executed and their last expression is
+returned.
+
+```thp
+val result = {
+    val temp = 161
+
+    temp * 2    // This will be assigned to `result`
+}
+
+print(result)   // 322
+```
 
diff --git a/src/pages/learn/flow-control/conditionals.md b/src/pages/learn/flow-control/conditionals.md
index 91337c2..369ff8d 100644
--- a/src/pages/learn/flow-control/conditionals.md
+++ b/src/pages/learn/flow-control/conditionals.md
@@ -44,6 +44,8 @@ if variable is Datatype
 
 ## If variable is of enum
 
+TBD
+
 ```thp
 val user_id = POST::get("user_id")
 
diff --git a/src/pages/learn/flow-control/loops.md b/src/pages/learn/flow-control/loops.md
index 338b95e..0432545 100644
--- a/src/pages/learn/flow-control/loops.md
+++ b/src/pages/learn/flow-control/loops.md
@@ -7,6 +7,8 @@ title: Loops
 
 ## For loop
 
+This is simmilar to PHP's `foreach`. There is no equivalent to PHP's `for`.
+
 Braces are required.
 
 ```thp
@@ -51,7 +53,7 @@ for value in collection
 
 ```thp
 val colors = ["red", "green", "blue"]
-val mut index = 0
+var index = 0
 
 while index < colors.size()
 {
diff --git a/src/pages/learn/functions/declaration.md b/src/pages/learn/functions/declaration.md
index 9a3d791..f08b659 100644
--- a/src/pages/learn/functions/declaration.md
+++ b/src/pages/learn/functions/declaration.md
@@ -5,6 +5,8 @@ title: Declaration
 
 # Declaration
 
+Function names **must** begin with a lowercase letter.
+
 
 ## No parameters, no return
 
diff --git a/src/pages/learn/index.md b/src/pages/learn/index.md
index ca817a5..08ef69e 100644
--- a/src/pages/learn/index.md
+++ b/src/pages/learn/index.md
@@ -11,13 +11,14 @@ pagesLayout:
   - path: variables
   - path: datatypes
   - path: comments
+  - path: operators
 - path: flow-control
   title: Flow control
   children:
-  - path: blocks
   - path: conditionals
   - path: loops
   - path: match
+  - path: blocks
 - path: data-structures
   title: Data structures
   children: