Updating documentation for Lindenmayer

.gitignore

@@ -49,7 +49,7 @@ Package.resolved
 .build/
 .swiftpm
 .vscode
-
+.docc-build/
 # CocoaPods
 #
 # We recommend against adding the Pods directory to your .gitignore. However

CLI_notes.md

@@ -0,0 +1,62 @@
+To build and view the documentation locally:
+
+```
+mkdir -p .build/symbol-graphs
+
+swift build --target Lindenmayer \
+--target LindenmayerViews \
+-Xswiftc -emit-symbol-graph \
+-Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs
+
+xcrun docc preview \
+--fallback-display-name Lindenmayer \
+--fallback-bundle-identifier Lindenmayer-swift \
+--fallback-bundle-version 0.1.0 \
+--additional-symbol-graph-dir .build/symbol-graphs
+```
+
+Should show something like:
+
+```
+========================================
+Starting Local Preview Server
+	 Address: http://localhost:8000/documentation/squirrel3
+	          http://localhost:8000/documentation/lindenmayer
+	          http://localhost:8000/documentation/lindenmayerviews
+	          http://localhost:8000/documentation/scenekitdebugtools
+========================================
+```
+
+
+To generate the HTML:
+
+```
+mkdir -p html
+xcrun docc convert \
+--output-path html \
+--fallback-display-name Lindenmayer \
+--fallback-bundle-identifier Lindenmayer-swift \
+--fallback-bundle-version 0.1.0 \
+--additional-symbol-graph-dir .build/symbol-graphs \
+```
+
+To get documentation coverage details:
+
+```
+xcrun docc convert \
+--fallback-display-name Lindenmayer \
+--fallback-bundle-identifier Lindenmayer-swift \
+--fallback-bundle-version 0.1.0 \
+--additional-symbol-graph-dir .build/symbol-graphs \
+--experimental-documentation-coverage \
+--level brief
+```
+
+
+```
+   --- Experimental coverage output enabled. ---
+                | Abstract        | Curated         | Code Listing
+Types           | 95% (112/118)   | 60% (71/118)    | 0.0% (0/118)
+Members         | 3.6% (350/9750) | 95% (9218/9750) | 0.0% (0/9750)
+Globals         | 41% (9/22)      | 91% (20/22)     | 0.0% (0/22)
+```

Package.swift

@@ -30,15 +30,15 @@ let package = Package(
     targets: [
         .target(
             name: "Lindenmayer",
-            dependencies: ["Squirrel3"]
+            dependencies: ["Squirrel3", "SceneKitDebugTools"]
         ),
         .target(
             name: "LindenmayerViews",
             dependencies: ["Lindenmayer", "SceneKitDebugTools"]
         ),
         .testTarget(
             name: "LindenmayerTests",
-            dependencies: ["Lindenmayer", "Squirrel3"]
+            dependencies: ["Lindenmayer", "Squirrel3", "SceneKitDebugTools"]
         ),
     ]
 )

Sources/Lindenmayer/Angle.swift

@@ -0,0 +1,68 @@
+//
+//  Angel.swift
+//
+//
+//  Created by Joseph Heck on 1/22/22.
+//
+
+import Foundation
+#if canImport(SwiftUI)
+    import SwiftUI
+    /// A geometric angle whose value you access in either radians or degrees.
+    public typealias Angle = SwiftUI.Angle
+#else
+    /// A geometric angle whose value you access in either radians or degrees.
+    public typealias Angle = SimpleAngle
+#endif
+
+/// A geometric angle whose value you access in either radians or degrees.
+///
+/// ## Topics
+///
+/// ### Creating an Angle
+///
+/// - ``degrees(_:)``
+/// - ``radians(_:)``
+/// - ``init(degrees:)``
+/// - ``init(radians:)``
+/// - ``init()``
+///
+/// ### Inspecting the value of an Angle
+///
+/// - ``degrees``
+/// - ``radians``
+///
+@frozen public struct SimpleAngle {
+    /// The value of the angle in radians.
+    public var radians: Double
+
+    /// The value of the angle in degrees.
+    @inlinable public var degrees: Double {
+        return radians * 180.0 / .pi
+    }
+
+    /// Creates a new Angle of zero radians.
+    @inlinable public init() {
+        radians = 0
+    }
+
+    /// Creates a new Angle with the value of radians you provide.
+    @inlinable public init(radians: Double) {
+        self.radians = radians
+    }
+
+    /// Creates a new Angle with the value of degrees you provide.
+    @inlinable public init(degrees: Double) {
+        radians = degrees * .pi / 180
+    }
+
+    /// Creates a new Angle with the value of radians you provide.
+    @inlinable public static func radians(_ radians: Double) -> Angle {
+        return Angle(radians: radians)
+    }
+
+    /// Creates a new Angle with the value of degrees you provide.
+    @inlinable public static func degrees(_ degrees: Double) -> Angle {
+        return Angle(degrees: degrees)
+    }
+}

Sources/Lindenmayer/BuiltinModules.swift

@@ -6,21 +6,29 @@
 //
 
 import Foundation
-import SwiftUI // for the 'Angle' type
 
 /// A namespace for a collection of built-in modules for use in L-systems.
+///
+///
+/// ## Topics
+///
+/// ### Built-in Modules
+///
+/// - ``Modules/Move``
+/// - ``Modules/Draw``
+/// - ``Modules/Branch``
+/// - ``Modules/EndBranch``
+/// - ``Modules/TurnLeft``
+/// - ``Modules/TurnRight``
+/// - ``Modules/PitchUp``
+/// - ``Modules/PitchDown``
+/// - ``Modules/RollLeft``
+/// - ``Modules/RollRight``
+/// - ``Modules/RollUpToVertical``
+///
 public enum Modules {}
 
 public extension Modules {
-    // MARK: - An Example module -
-
-    struct Internode: Module {
-        // This is the kind of thing that I want external developers using the library to be able to create to represent elements within their L-system.
-        public var name = "I"
-        public var render2D: [TwoDRenderCmd] = [RenderCommand.Draw(length: 10)] // draws a line 10 units long
-        public init() {}
-    }
-
     // MARK: - Built-in Modules that are effectively wrappers around specific rendering commands
 
     /// A module that informs a renderer to turn left while rendering the L-system.

Sources/Lindenmayer/LSystemBasic.swift → Sources/Lindenmayer/ContextualLSystem.swift

@@ -1,5 +1,5 @@
 //
-//  LSystemBasic.swift
+//  ContextualLSystem.swift
 //
 //
 //  Created by Joseph Heck on 1/1/22.
@@ -10,15 +10,59 @@ import Foundation
 /// A basic Lindenmayer system.
 ///
 /// The basic Lindenmayer system doesn't use external parameters or a seed-able random number generator within its rules.
-/// If you want to create an L-system that uses a seed-able random number generator, use ``LSystemRNG``.
-/// If you want to create an L-system that uses a set of external parameters and a seed-able random number generator, use ``LSystemDefinesRNG``.
+/// If you want to create an L-system that uses a seed-able random number generator, use ``RandomContextualLSystem``.
+/// If you want to create an L-system that uses a set of external parameters and a seed-able random number generator, use ``ParameterizedRandomContextualLSystem``.
 ///
 /// For more information on the background of Lindenmayer systems, see [Wikipedia's L-System](https://en.wikipedia.org/wiki/L-system).
-
-public struct LSystemBasic: LSystem {
+///
+/// ## Topics
+///
+/// ### Creating and Updating L-systems
+///
+/// - ``ContextualLSystem/init(_:state:newStateIndicators:rules:)``
+/// - ``ContextualLSystem/updatedLSystem(with:newItemIndicators:)``
+///
+/// ### Inspecting L-systems
+///
+/// - ``ContextualLSystem/state``
+/// - ``ContextualLSystem/state(at:)``
+/// - ``ContextualLSystem/newStateIndicators``
+///
+/// ### Adding Rules to an L-system
+///
+/// - ``ContextualLSystem/rewrite(_:produces:)``
+/// - ``ContextualLSystem/rewrite(_:where:produces:)``
+/// - ``ContextualLSystem/rules``
+///
+/// ### Adding Contextual Rules to an L-system
+///
+/// - ``ContextualLSystem/rewrite(leftContext:directContext:produces:)``
+/// - ``ContextualLSystem/rewrite(directContext:rightContext:produces:)``
+/// - ``ContextualLSystem/rewrite(leftContext:directContext:rightContext:produces:)``
+///
+/// ### Adding Contextual Rules with an evaluation closure to an L-system
+///
+/// - ``ContextualLSystem/rewrite(leftContext:directContext:where:produces:)``
+/// - ``ContextualLSystem/rewrite(directContext:rightContext:where:produces:)``
+/// - ``ContextualLSystem/rewrite(leftContext:directContext:rightContext:where:produces:)``
+///
+/// ### Evolving the L-system
+///
+/// - ``ContextualLSystem/evolve()``
+/// - ``ContextualLSystem/evolved(iterations:)``
+///
+/// ### Resetting L-systems to their initial state
+///
+/// - ``ContextualLSystem/reset()``
+public struct ContextualLSystem: LindenmayerSystem {
     let axiom: [Module]
+
     /// The sequence of modules that represents the current state of the L-system.
     public let state: [Module]
+
+    /// An array of Boolean values that indicate if the state in the L-system was newly created in the evolution.
+    ///
+    /// This array is primarily used for debugging purposes
     public var newStateIndicators: [Bool]
 
     /// The sequence of rules that the L-system uses to process and evolve its state.
@@ -30,6 +74,16 @@ public struct LSystemBasic: LSystem {
     ///   - parameters: A set of parameters accessible to rules for evaluation and production.
     ///   - prng: A psuedo-random number generator to use for stochastic rule productions.
     ///   - rules: A collection of rules that the Lindenmayer system applies when you call the evolve function.
+    ///
+    /// Convenient initializers for creating contextual L-systems uses ``LSystem``, calling ``LSystem/create(_:)-632a3``, or ``LSystem/create(_:)-12ubu``.
+    /// For example:
+    /// ```
+    /// struct A: Module {
+    ///     public var name = "A"
+    /// }
+    ///
+    /// let algae = Lsystem.create(A())
+    /// ```
     public init(_ axiom: [Module],
                 state: [Module]?,
                 newStateIndicators: [Bool]?,
@@ -56,18 +110,20 @@ public struct LSystemBasic: LSystem {
     /// - Parameter state: The sequence of modules that represent the new state.
     /// - Returns: A new L-system with the updated state that has the same rules.
     ///
-    /// This function is called from the common LSystem protocol's default implementation to generate an updated
+    /// This function is called from the common ``LindenmayerSystem`` protocol's default implementation to generate an updated
     /// L-system with a set of new modules.
     public func updatedLSystem(with state: [Module], newItemIndicators: [Bool]) -> Self {
-        return LSystemBasic(axiom, state: state, newStateIndicators: newItemIndicators, rules: rules)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newItemIndicators, rules: rules)
     }
-
+
+    /// Resets the L-system to it's initial state, wiping out an existing state while keeping the rules.
+    /// - Returns: A new L-system with it's state reset to the initial state you set when you created the L-system.
     public func reset() -> Self {
-        return LSystemBasic(axiom, state: nil, newStateIndicators: newStateIndicators, rules: rules)
+        return ContextualLSystem(axiom, state: nil, newStateIndicators: newStateIndicators, rules: rules)
     }
 }
 
-public extension LSystemBasic {
+public extension ContextualLSystem {
     /// Adds a rewriting rule to the L-System.
     /// - Parameters:
     ///   - direct: The type of module that the rule matches
@@ -81,7 +137,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleDirect(direct: direct, where: evalClosure, produce: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -95,7 +151,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleDirect(direct: direct, where: nil, produce: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -111,7 +167,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleLeftDirect(leftType: leftContext, directType: directContext, where: evalClosure, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -125,7 +181,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleLeftDirect(leftType: leftContext, directType: directContext, where: nil, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -141,7 +197,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleDirectRight(directType: directContext, rightType: rightContext, where: evalClosure, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -155,7 +211,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleDirectRight(directType: directContext, rightType: rightContext, where: nil, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -171,7 +227,7 @@ public extension LSystemBasic {
         let newRule = RewriteRuleLeftDirectRight(leftType: leftContext, directType: directContext, rightType: rightContext, where: evalClosure, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 
     /// Adds a rewriting rule to the L-System.
@@ -185,6 +241,6 @@ public extension LSystemBasic {
         let newRule = RewriteRuleLeftDirectRight(leftType: leftContext, directType: directContext, rightType: rightContext, where: nil, produces: produceClosure)
         var newRuleSet: [Rule] = rules
         newRuleSet.append(contentsOf: [newRule])
-        return LSystemBasic(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
+        return ContextualLSystem(axiom, state: state, newStateIndicators: newStateIndicators, rules: newRuleSet)
     }
 }