Added some documentation to some ./examples/*.fun scripts.

README.md

@@ -64,3 +64,6 @@ A language that feels like home for developers who:
 
 Fun may not change the world — but it will make programming a little more fun.
 
+## To do
+
+Everything... ;) No, a lot of stuff works already, but only a very small set of functions are available in the Fun programming language. It grows from day to day...

examples/arrays.fun

@@ -8,7 +8,18 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Arrays Example
+ *
+ * Demonstrates basic array operations including:
+ * - Array declaration and initialization
+ * - Accessing elements via indexing
+ * - Iterating through arrays with `for` loops
+ * - Creating subarrays (slices)
+ *- Length calculation
+ */
+
 // Arrays basics
 arr = [1, 2, 3]
 print(arr)                 // -> [1, 2, 3]

examples/arrays_advanced.fun

@@ -8,7 +8,18 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Advanced Arrays Example
+ *
+ * Covers more complex array features such as:
+ * - Multi-dimensional arrays
+ * - Array concatenation and splitting
+ * - Repeating elements in arrays
+ * - Array comprehensions with transformations
+ * - Working with nested arrays
+ */
+
 // Advanced Arrays Demo
 
 // Start with a basic array

examples/arrays_iter.fun

@@ -8,7 +8,18 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Array Iteration Examples
+ *
+ * Focuses specifically on:
+ * - Various iteration methods (`for`, `while`)
+ * - Using array mapping functions
+ * - Filtering arrays based on conditions
+ * - Reducing arrays to computed values
+ *- Converting between different collection types during iteration
+ */
+
 // for-in over an array literal
 for x in [1, 2, 3]
   print(x)                 // prints: 1, then 2, then 3

examples/builtins_conversions.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Built-in Type Conversions
+ *
+ * Shows how FunScript handles:
+ * - Implicit type conversions (numeric, string)
+ * - Explicit casting operations
+ * - Conversion functions and operators
+ * - Handling of special cases in conversions
+ */
+
 // Conversions and length built-ins demo
 
 // len on array and string

examples/builtins_extended.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * # Extended Built-ins Examples
+ *
+ * Demonstrates advanced usage of built-in types including:
+ * - Customizing default behaviors with `default` keyword
+ * - Working with large integer values (beyond standard limits)
+ * - Implementing type-specific extensions
+ *- Handling edge cases in conversions and operations
+*/
+
 // Built-ins: strings, array utils, iteration helpers, and math
 
 // Strings

examples/builtins_maps_and_more.fun

@@ -8,7 +8,18 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Maps Implementation Examples
+ *
+ * Covers:
+ * - Map declaration syntax (`map<K, V>`)
+ * - Key-value pair manipulation
+ * - Iterating through maps with `for`
+ * - Nested map structures
+ * - Converting between different collection types
+ */
+
 // Maps, map/filter/reduce, labeled break/continue (depth), and file I/O
 
 // Map literal and indexing

examples/expressions_test.fun

@@ -8,7 +8,18 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Expression Testing Suite
+ *
+ * Contains comprehensive tests for:
+ * - Operator precedence rules
+ * - Arithmetic expression evaluation
+ * - Logical expressions (AND, OR)
+ * - Conditional expressions (`if`, `else`)
+ * - Expression short-circuiting behavior
+ */
+
 // Expressions test: arithmetic, precedence, comparisons, logical ops, unary, parentheses.
 
 print("=== Expressions test start ===")

examples/file_io.fun

@@ -9,6 +9,16 @@
  * https://opensource.org/license/isc-license-txt
  */
 
+/*
+ * File Input/Output Examples
+ *
+ * Demonstrates:
+ * - Reading from files with `open`
+ * - Writing to output files
+ * - Working with file streams and handles
+ * - Error handling during I/O operations
+ */
+
 // file I/O (writes then reads)
 path = "/tmp/fun_io_example.txt"
 ok = write_file(path, "hello-io")

examples/file_print_for_file_line_by_line.fun

@@ -9,6 +9,16 @@
  * https://opensource.org/license/isc-license-txt
  */
 
+/*
+ * Line-by-Line File Processing
+ *
+ * Shows techniques for:
+ * - Reading files line by line using `readline`
+ * - Conditional processing based on line content
+ * - Maintaining state between lines (e.g., counters)
+ * - Implementing custom file formatters
+ */
+
 print("=== Line-by-line print start ===")
 
 string file = "/etc/passwd"

examples/for_range_test.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * For Loop Range Testing
+ *
+ * Focuses specifically on:
+ * - Using the `range` keyword with for loops
+ * - Nested range loops and their optimizations
+ * - Range-based iteration patterns
+ * - Comparison between traditional ranges and modern implementations
+ */
+
 // for/range test: globals, nested loops, and a function using range
 
 print("=== for/range test start ===")

examples/functions_test.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Function Definition Testing
+ *
+ * Covers:
+ * - Basic function syntax (`def`)
+ * - Handling multiple parameter types
+ * - Function return value testing
+ * - Function composition examples
+ */
+
 // Functions test: definitions, calls, parameters, locals, returns, and if/else.
 
 print("=== Functions test start ===")

examples/have_fun.fun

@@ -8,7 +8,7 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
 /*
  * Have fun in Fun
  */

examples/have_fun_function.fun

@@ -8,7 +8,7 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
 // Have fun in Fun
 
 string s = "Have fun!"

examples/if_else_test.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Conditional Logic Testing Suite
+ *
+ * Tests various aspects of conditional execution including:
+ * - Basic if/else structures
+ * - Nested conditional statements
+ * - Ternary operator usage (`? :`)
+ * - Comparison conditionals with different operators
+ */
+
 // Test else / else if chains and nested if-blocks (two-space indentation)
 
 print("=== if/else-if/else test ===")

examples/loops_break_continue.fun

@@ -8,7 +8,17 @@
  * Licensed under the terms of the ISC license.
  * https://opensource.org/license/isc-license-txt
  */
- 
+
+/*
+ * Loop Control Flow Examples
+ *
+ * Focuses on:
+ * - Using break to exit loops prematurely
+ * - Implementing continue for skipping iterations
+ * - Creating complex loop control patterns
+ * - Handling infinite loops and their termination conditions
+ */
+
 // break and continue examples
 
 // 1) while loop: print odd numbers, stop after printing 7