fixing main documentation

Author: leogdion

Scripts/validate-docs.sh

@@ -316,27 +316,54 @@ validate_code_examples() {
 
         echo -e "${BLUE}📄 Processing: $relative_path${NC}"
 
-        # Extract Swift code blocks using awk
+        # Extract Swift code blocks using awk, respecting skip markers
         awk -v temp_dir="$temp_dir" -v file_base="$(basename "$file" .md)" '
-            BEGIN { block_num = 0 }
+            BEGIN { block_num = 0; skip_block = 0 }
+            
+            # Check for skip markers in HTML comments
+            /<!-- (skip-test|no-test|incomplete|example-only) -->/ {
+                skip_block = 1
+                next
+            }
+            
             /^```swift/ { 
                 in_swift = 1
-                block_num++
-                output_file = temp_dir "/" file_base "_" block_num ".swift"
-                print "import Foundation" > output_file
-                print "import SyntaxKit" >> output_file
-                print "" >> output_file
+                
+                # Check preceding lines (up to 3 lines back) for skip markers
+                for (i = NR - 3; i < NR; i++) {
+                    if (i > 0 && lines[i] ~ /<!-- (skip-test|no-test|incomplete|example-only) -->/) {
+                        skip_block = 1
+                        break
+                    }
+                }
+                
+                if (!skip_block) {
+                    block_num++
+                    output_file = temp_dir "/" file_base "_" block_num ".swift"
+                    print "import Foundation" > output_file
+                    print "import SyntaxKit" >> output_file
+                    print "" >> output_file
+                }
                 next 
             }
             /^```$/ && in_swift { 
                 in_swift = 0
-                close(output_file)
-                print output_file
+                if (!skip_block && output_file) {
+                    close(output_file)
+                    print output_file
+                }
+                skip_block = 0
+                output_file = ""
                 next 
             }
-            in_swift { 
-                print $0 >> output_file 
+            in_swift && !skip_block { 
+                if (output_file) {
+                    print $0 >> output_file 
+                }
             }
+            
+            # Store lines for lookback
+            { lines[NR] = $0 }
         ' "$file"
     }
 

Sources/SyntaxKit/Documentation.docc/Documentation.md

@@ -129,29 +129,30 @@ let structExample = Struct("BlackjackCard") {
             Variable(.let, name: "second", type: "Int?")
         }
 
-        ComputedProperty("values") {
+        ComputedProperty("values", type: "Values") {
             Switch("self") {
                 SwitchCase(".ace") {
                     Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "1")
-                            Parameter(name: "second", value: "11")
+                          
+                            ParameterExp(name: "first", value: Literal.integer(1))
+                          ParameterExp(name: "second", value: Literal.integer(11))
                         }
                     }
                 }
                 SwitchCase(".jack", ".queen", ".king") {
                     Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "10")
-                            Parameter(name: "second", value: "nil")
+                          ParameterExp(name: "first", value: Literal.integer(10))
+                          ParameterExp(name: "second", value: Literal.nil)
                         }
                     }
                 }
                 Default {
                     Return {
                         Init("Values") {
-                            Parameter(name: "first", value: "self.rawValue")
-                            Parameter(name: "second", value: "nil")
+                          ParameterExp(name: "first", value: VariableExp("self.rawValue"))
+                          ParameterExp(name: "second", value: Literal.nil)
                         }
                     }
                 }
@@ -169,11 +170,19 @@ let structExample = Struct("BlackjackCard") {
         Line("BlackjackCard properties and methods")
     }
 
-    ComputedProperty("description") {
-        VariableDecl(.var, name: "output", equals: "\"suit is \\(suit.rawValue),\"")
-        PlusAssign("output", "\" value is \\(rank.values.first)\"")
+    ComputedProperty("description", type: "String") {
+        Variable(.var, name: "output", equals: "\"suit is \\(suit.rawValue),\"")
+        Infix(
+          .plusAssign,
+          lhs: VariableExp("output"),
+          rhs: Literal.string("\" value is \\(rank.values.first)\"")
+        )
         If(Let("second", "rank.values.second"), then: {
-            PlusAssign("output", "\" or \\(second)\"")
+          Infix(
+            .plusAssign,
+            lhs: VariableExp("output"),
+            rhs: Literal.string("\" or \\(second)\"")
+          )
         })
         Return {
             VariableExp("output")
@@ -339,7 +348,7 @@ struct MembersMacro: MemberMacro {
 ```
 
 **SyntaxKit Approach (Clean and readable):**
-<!-- example-only -->
+<!-- skip-test -->
 ```swift
 struct MembersMacro: MemberMacro {
     static func expansion(
@@ -356,8 +365,7 @@ struct MembersMacro: MemberMacro {
                 for variable in variables {
                     Parameter(variable.name, type: variable.type)
                 }
-            }
-            .body {
+            } _: {
                 for variable in variables {
                     Assignment("self.\(variable.name)", variable.name)
                 }
@@ -396,6 +404,7 @@ struct MembersMacro: MemberMacro {
 
 **Generated code performance is identical to hand-written Swift.** SyntaxKit operates at compile-time only:
 
+<!-- skip-test -->
 ```swift
 // SyntaxKit-generated code
 struct User: Equatable {

Sources/SyntaxKit/Documentation.docc/Examples/EnumGenerator.md

@@ -446,10 +446,3 @@ SyntaxKit's enum generator transforms tedious manual maintenance into reliable a
 - **Improved developer experience** and satisfaction
 
 The approach scales from small personal projects to enterprise applications with hundreds of API endpoints. Once implemented, enum maintenance becomes completely automated, freeing developers to focus on building great features instead of maintaining boilerplate code.
-
-## Related Examples
-
-- ``Examples/API-Endpoints`` - Simple endpoint enum generation
-- ``Examples/Error-Handling`` - Complex error enum with associated values
-- ``Examples/Configuration-Driven`` - Multiple enum generation from single config
-- ``Tutorials/Code-Generation`` - Comprehensive code generation patterns

Sources/SyntaxKit/Expressions/Infix.swift

@@ -37,6 +37,8 @@ public struct Infix: CodeBlock, ExprCodeBlock {
     case lessThan = "<"
     case equal = "=="
     case notEqual = "!="
+    case plusAssign = "+="
+    case minusAssign = "-="
 
     /// The string representation of the operator.
     public var symbol: String {