improve docs with examples

Author: Chemaclass

.gitignore

@@ -9,6 +9,7 @@ node_modules/
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+phel-error.log
 
 .DS_Store
 Thumbs.db

content/documentation/arithmetic.md

@@ -12,6 +12,24 @@ All arithmetic operators are entered in prefix notation.
 (+ 1 (* 2 2) (/ 10 5) 3 4 (- 5 6)) # Evaluates to 13
 ```
 
+{% php_note() %}
+Phel uses prefix notation (operator comes first) instead of PHP's infix notation:
+
+```php
+// PHP - infix notation
+1 + (2 * 2) + (10 / 5) + 3 + 4 + (5 - 6);
+
+// Phel - prefix notation
+(+ 1 (* 2 2) (/ 10 5) 3 4 (- 5 6))
+```
+
+This allows operators to accept any number of arguments and eliminates operator precedence concerns.
+{% end %}
+
+{% clojure_note() %}
+Arithmetic works exactly like Clojure—prefix notation with variadic support for most operators.
+{% end %}
+
 Some operators support zero, one or multiple arguments.
 
 ```phel
@@ -34,6 +52,27 @@ Some operators support zero, one or multiple arguments.
 (/ 24 4 2) #Evaluates to 3
 ```
 
+{% php_note() %}
+Phel's variadic operators are more flexible than PHP's:
+
+```php
+// PHP - requires at least two operands
+1 + 2 + 3 + 4 + 5;
+// Can't do this: +();  <- syntax error
+
+// Phel - supports 0, 1, or many operands
+(+)                     # 0 (identity)
+(+ 1)                   # 1 (identity)
+(+ 1 2 3 4 5)          # 15 (sum of all)
+```
+
+**Useful patterns:**
+- `(+)` returns the additive identity (0)
+- `(*)` returns the multiplicative identity (1)
+- `(- x)` negates a number
+- `(/ x)` computes the reciprocal
+{% end %}
+
 Further numeric operations are `%` to compute the remainder of two values and `**` to raise a number to the power. All numeric operations can be found in the API documentation.
 
 Some numeric operations can result in an undefined or unrepresentable value. These values are called _Not a Number_ (NaN). Phel represents these values by the constant `NAN`. You can check if a result is NaN by using the `nan?` function.
@@ -44,6 +83,24 @@ Some numeric operations can result in an undefined or unrepresentable value. The
 (nan? NAN) # true
 ```
 
+{% php_note() %}
+NaN handling is similar to PHP:
+
+```php
+// PHP
+is_nan(1);           // false
+is_nan(log(-1));     // true
+is_nan(NAN);         // true
+
+// Phel
+(nan? 1)             # false
+(nan? (php/log -1))  # true
+(nan? NAN)           # true
+```
+
+The `%` operator for remainder and `**` for exponentiation work like PHP's `%` and `**` operators.
+{% end %}
+
 ## Bitwise Operators
 
 Phel allows the evaluation and manipulation of specific bits within an integer.
@@ -80,3 +137,31 @@ Phel allows the evaluation and manipulation of specific bits within an integer.
 (bit-test 0b1011 0) # Evaluates to true
 (bit-test 0b1011 2) # Evaluates to false
 ```
+
+{% php_note() %}
+Phel provides named functions for bitwise operations instead of PHP's operators:
+
+```php
+// PHP bitwise operators
+0b1100 & 0b1001;      // AND
+0b1100 | 0b1001;      // OR
+0b1100 ^ 0b1001;      // XOR
+~0b0111;              // NOT
+0b1101 << 1;          // Left shift
+0b1101 >> 1;          // Right shift
+
+// Phel named functions
+(bit-and 0b1100 0b1001)
+(bit-or 0b1100 0b1001)
+(bit-xor 0b1100 0b1001)
+(bit-not 0b0111)
+(bit-shift-left 0b1101 1)
+(bit-shift-right 0b1101 1)
+```
+
+Phel also provides additional bit manipulation functions not available in PHP: `bit-set`, `bit-clear`, `bit-flip`, and `bit-test`.
+{% end %}
+
+{% clojure_note() %}
+Bitwise operators work exactly like Clojure's—same function names and behavior for bit manipulation.
+{% end %}

content/documentation/basic-types.md

@@ -60,19 +60,15 @@ A keyword is like a symbol that begins with a colon character. However, it is us
 ::
 ```
 
-Keywords are commonly used as map keys and function options:
+Keywords are commonly used as map keys:
 
 ```phel
-# Map keys
+# Map with keyword keys
 {:name "Alice" :email "[email protected]"}
 
-# Function arguments for options
-(defn greet [name & {:keys [formal?]}]
-  (if formal?
-    (str "Good day, " name)
-    (str "Hey, " name)))
-
-(greet "Alice" :formal? true)  # => "Good day, Alice"
+# Accessing map values with keywords
+(get {:name "Alice" :age 30} :name)  # => "Alice"
+(:name {:name "Alice" :age 30})      # => "Alice" (keywords are functions!)
 ```
 
 {% php_note() %}