docs: Turtle.LSystem improvement ( Fixes #116 )

Improving parameter docs and inner docs

Author: StartAutomating

Turtle.types.ps1xml

@@ -724,50 +724,61 @@ $Order = 2,
 $Variable = @{}
 )
 
+# First, let us expand our axiom
 $currentState = "$Axiom"
+# (at least, as long as we're supposed to)
 if ($Order -ge 1) {
     $combinedPattern = "(?>$($Rule.Keys -join '|'))"
     foreach ($iteration in 1..$Order) {
+        # To expand each iteration, we replace any matching characters
         $currentState = $currentState -replace $combinedPattern, {
             $match = $_
             $matchingRule = $rule["$match"]
+            # a matching rule could be dynamically specified with a script block
             if ($matchingRule -is [ScriptBlock]) {
                 return "$(. $matchingRule $match)"
             } else {
+                # but is often statically expanded with a string.
                 return $matchingRule
             }
         }    
     }        
 }
 
-$localReplacement = [Ordered]@{}
-foreach ($key in $variable.Keys) {
-    $localReplacement[$key] = 
-        if ($variable[$key] -is [ScriptBlock]) {
-            [ScriptBlock]::Create($variable[$key])
-        } else {
-            $variable[$key]
-        }
-}
-
+# Now we know our final state
 $finalState = $currentState
 
+# and can add the appropriate data attributes.
 $this.PathAttribute = [Ordered]@{
     "data-l-order" = $Order
     "data-l-axiom" = $Axiom
     "data-l-rules" = ConvertTo-Json $Rule 
     "data-l-expanded" = $finalState
 }
 
+# Next, prepare our replacements.
+# The provided script block will almost always be scoped differently
+# so we need to recreate it.
+$localReplacement = [Ordered]@{}
+foreach ($key in $variable.Keys) {
+    $localReplacement[$key] =
+        if ($variable[$key] -is [ScriptBlock]) {
+            [ScriptBlock]::Create($variable[$key])
+        } else {
+            $variable[$key]
+        }
+}
+
+# Now we need to find all potential matches
 $MatchesAny = "(?>$($variable.Keys -join '|'))"
 $allMatches = @([Regex]::Matches($finalState, $MatchesAny, 'IgnoreCase,IgnorePatternWhitespace'))
+# we want to minimize rematching, so create a temporary cache.
 $matchCache = @{}
 :nextMatch foreach ($match in $allMatches) {
     $m = "$match"
     if (-not $matchCache[$m]) {
         foreach ($key in $Variable.Keys) {
-            if (-not ($match -match $key)) { continue }
-            # if ($variable[$key] -isnot [ScriptBlock]) { continue }
+            if (-not ($match -match $key)) { continue }     
             $matchCache[$m] = $localReplacement[$key]
             break
         }