From 61905dc13b0f75d2e6abd84af58ddb5a3c25714e Mon Sep 17 00:00:00 2001
From: leogdion <leogdion@brightdigit.com>
Date: Tue, 17 Jun 2025 09:30:00 -0400
Subject: [PATCH 1/3] Adding docc file

---
 .gitignore                                    |   3 +-
 .../Documentation.docc/Documentation.md       | 217 ++++++++++++++++++
 2 files changed, 219 insertions(+), 1 deletion(-)
 create mode 100644 Sources/SyntaxKit/Documentation.docc/Documentation.md

diff --git a/.gitignore b/.gitignore
index 2640454..95334f2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -136,4 +136,5 @@ Support/*/macOS.entitlements
 vendor/ruby
 public
 .mint
-*.lcov
\ No newline at end of file
+*.lcov
+.docc-build
\ No newline at end of file
diff --git a/Sources/SyntaxKit/Documentation.docc/Documentation.md b/Sources/SyntaxKit/Documentation.docc/Documentation.md
new file mode 100644
index 0000000..24431e9
--- /dev/null
+++ b/Sources/SyntaxKit/Documentation.docc/Documentation.md
@@ -0,0 +1,217 @@
+# ``SyntaxKit``
+
+SyntaxKit is a Swift package that allows developers to build Swift code using result builders. It provides a declarative way to generate Swift code structures using SwiftSyntax.
+
+## Overview
+
+SyntaxKit provides a set of result builders that allow you to create Swift code structures in a declarative way. Here's an example:
+
+```swift
+import SyntaxKit
+
+let code = Struct("BlackjackCard") {
+    Enum("Suit") {
+        EnumCase("spades").equals("♠")
+        EnumCase("hearts").equals("♡")
+        EnumCase("diamonds").equals("♢")
+        EnumCase("clubs").equals("♣")
+    }
+    .inherits("Character")
+    .comment("nested Suit enumeration")
+}
+
+let generatedCode = code.generateCode()
+```
+
+This will generate the following Swift code:
+
+```swift
+struct BlackjackCard {
+    // nested Suit enumeration
+    enum Suit: Character {
+        case spades = "♠"
+        case hearts = "♡"
+        case diamonds = "♢"
+        case clubs = "♣"
+    }
+}
+```
+
+## Topics
+
+### Declarations
+
+- ``Struct``
+- ``Enum``
+- ``EnumCase``
+- ``Function``
+- ``Init``
+- ``ComputedProperty``
+- ``VariableDecl``
+- ``Let``
+- ``Variable``
+
+### Expressions & Statements
+- ``Assignment``
+- ``PlusAssign``
+- ``Return``
+- ``VariableExp``
+
+### Control Flow
+- ``If``
+- ``Switch``
+- ``SwitchCase``
+- ``Default``
+
+### Building Blocks
+- ``CodeBlock``
+- ``Parameter``
+- ``Literal``
+
+## Full Example
+
+Here is a more comprehensive example that demonstrates many of SyntaxKit's features to generate a `BlackjackCard` struct.
+
+### DSL Code
+
+```swift
+import SyntaxKit
+
+let structExample = Struct("BlackjackCard") {
+    Enum("Suit") {
+        EnumCase("spades").equals("♠")
+        EnumCase("hearts").equals("♡")
+        EnumCase("diamonds").equals("♢")
+        EnumCase("clubs").equals("♣")
+    }
+    .inherits("Character")
+    .comment("nested Suit enumeration")
+
+    Enum("Rank") {
+        EnumCase("two").equals(2)
+        EnumCase("three")
+        EnumCase("four")
+        EnumCase("five")
+        EnumCase("six")
+        EnumCase("seven")
+        EnumCase("eight")
+        EnumCase("nine")
+        EnumCase("ten")
+        EnumCase("jack")
+        EnumCase("queen")
+        EnumCase("king")
+        EnumCase("ace")
+        
+        Struct("Values") {
+            Variable(.let, name: "first", type: "Int")
+            Variable(.let, name: "second", type: "Int?")
+        }
+        
+        ComputedProperty("values") {
+            Switch("self") {
+                SwitchCase(".ace") {
+                    Return {
+                        Init("Values") {
+                            Parameter(name: "first", value: "1")
+                            Parameter(name: "second", value: "11")
+                        }
+                    }
+                }
+                SwitchCase(".jack", ".queen", ".king") {
+                    Return {
+                        Init("Values") {
+                            Parameter(name: "first", value: "10")
+                            Parameter(name: "second", value: "nil")
+                        }
+                    }
+                }
+                Default {
+                    Return {
+                        Init("Values") {
+                            Parameter(name: "first", value: "self.rawValue")
+                            Parameter(name: "second", value: "nil")
+                        }
+                    }
+                }
+            }
+        }
+    }
+    .inherits("Int")
+    .comment("nested Rank enumeration")
+
+    Variable(.let, name: "rank", type: "Rank")
+    Variable(.let, name: "suit", type: "Suit")
+    .comment("BlackjackCard properties and methods")
+
+    ComputedProperty("description") {
+        VariableDecl(.var, name: "output", equals: "\"suit is \\(suit.rawValue),\"")
+        PlusAssign("output", "\" value is \\(rank.values.first)\"")
+        If(Let("second", "rank.values.second"), then: {
+            PlusAssign("output", "\" or \\(second)\"")
+        })
+        Return {
+            VariableExp("output")
+        }
+    }
+}
+```
+
+### Generated Code
+
+```swift
+import Foundation
+
+struct BlackjackCard {
+  // nested Suit enumeration
+  enum Suit: Character {
+    case spades = "♠"
+    case hearts = "♡"
+    case diamonds = "♢"
+    case clubs = "♣"
+  }
+
+  // nested Rank enumeration
+  enum Rank: Int {
+    case two = 2
+    case three
+    case four
+    case five
+    case six
+    case seven
+    case eight
+    case nine
+    case ten
+    case jack
+    case queen
+    case king
+    case ace
+
+    struct Values {
+      let first: Int, second: Int?
+    }
+
+    var values: Values {
+      switch self {
+      case .ace:
+        return Values(first: 1, second: 11)
+      case .jack, .queen, .king:
+        return Values(first: 10, second: nil)
+      default:
+        return Values(first: self.rawValue, second: nil)
+      }
+    }
+  }
+
+  // BlackjackCard properties and methods
+  let rank: Rank
+  let suit: Suit
+  var description: String {
+    var output = "suit is \\(suit.rawValue),"
+    output += " value is \\(rank.values.first)"
+    if let second = rank.values.second {
+      output += " or \\(second)"
+    }
+    return output
+  }
+}
+```
\ No newline at end of file

From 63f889121a5e4e0032cfbbc3b65417734a5625a5 Mon Sep 17 00:00:00 2001
From: leogdion <leogdion@brightdigit.com>
Date: Tue, 17 Jun 2025 09:42:52 -0400
Subject: [PATCH 2/3] Adding more comments

---
 Sources/SyntaxKit/Assignment.swift            |  6 ++++
 Sources/SyntaxKit/Case.swift                  |  5 ++++
 Sources/SyntaxKit/CodeBlock+Generate.swift    |  2 ++
 Sources/SyntaxKit/CodeBlock.swift             | 13 +++++++++
 Sources/SyntaxKit/CommentBuilderResult.swift  | 10 +++++--
 Sources/SyntaxKit/ComputedProperty.swift      |  6 ++++
 Sources/SyntaxKit/Default.swift               |  4 +++
 Sources/SyntaxKit/Enum.swift                  | 17 +++++++++++
 Sources/SyntaxKit/Function.swift              | 16 ++++++++++
 Sources/SyntaxKit/Group.swift                 |  3 ++
 Sources/SyntaxKit/If.swift                    |  6 ++++
 Sources/SyntaxKit/Init.swift                  |  6 ++++
 Sources/SyntaxKit/Let.swift                   |  6 ++++
 Sources/SyntaxKit/Line.swift                  | 11 +++++--
 Sources/SyntaxKit/Literal.swift               |  6 ++++
 Sources/SyntaxKit/Parameter.swift             |  7 +++++
 .../SyntaxKit/ParameterBuilderResult.swift    |  6 ++++
 Sources/SyntaxKit/ParameterExp.swift          |  5 ++++
 .../SyntaxKit/ParameterExpBuilderResult.swift |  6 ++++
 Sources/SyntaxKit/PlusAssign.swift            |  5 ++++
 Sources/SyntaxKit/Return.swift                |  4 +++
 Sources/SyntaxKit/Struct.swift                |  9 ++++++
 Sources/SyntaxKit/Switch.swift                |  5 ++++
 Sources/SyntaxKit/SwitchCase.swift            |  5 ++++
 Sources/SyntaxKit/Trivia+Comments.swift       |  6 ++--
 Sources/SyntaxKit/Variable.swift              |  7 +++++
 Sources/SyntaxKit/VariableDecl.swift          |  6 ++++
 Sources/SyntaxKit/VariableExp.swift           | 29 +++++++++++++++++++
 Sources/SyntaxKit/VariableKind.swift          |  3 ++
 29 files changed, 214 insertions(+), 6 deletions(-)

diff --git a/Sources/SyntaxKit/Assignment.swift b/Sources/SyntaxKit/Assignment.swift
index 7fb5894..4a0af2e 100644
--- a/Sources/SyntaxKit/Assignment.swift
+++ b/Sources/SyntaxKit/Assignment.swift
@@ -29,9 +29,15 @@
 
 import SwiftSyntax
 
+/// An assignment expression.
 public struct Assignment: CodeBlock {
   private let target: String
   private let value: String
+
+  /// Creates an assignment expression.
+  /// - Parameters:
+  ///   - target: The variable to assign to.
+  ///   - value: The value to assign.
   public init(_ target: String, _ value: String) {
     self.target = target
     self.value = value
diff --git a/Sources/SyntaxKit/Case.swift b/Sources/SyntaxKit/Case.swift
index 2358b41..2ff34da 100644
--- a/Sources/SyntaxKit/Case.swift
+++ b/Sources/SyntaxKit/Case.swift
@@ -29,10 +29,15 @@
 
 import SwiftSyntax
 
+/// A `case` in a `switch` statement with tuple-style patterns.
 public struct Case: CodeBlock {
   private let patterns: [String]
   private let body: [CodeBlock]
 
+  /// Creates a `case` for a `switch` statement.
+  /// - Parameters:
+  ///   - patterns: The patterns to match for the case.
+  ///   - content: A ``CodeBlockBuilder`` that provides the body of the case.
   public init(_ patterns: String..., @CodeBlockBuilderResult content: () -> [CodeBlock]) {
     self.patterns = patterns
     self.body = content()
diff --git a/Sources/SyntaxKit/CodeBlock+Generate.swift b/Sources/SyntaxKit/CodeBlock+Generate.swift
index 7fcb330..c912232 100644
--- a/Sources/SyntaxKit/CodeBlock+Generate.swift
+++ b/Sources/SyntaxKit/CodeBlock+Generate.swift
@@ -31,6 +31,8 @@ import Foundation
 import SwiftSyntax
 
 extension CodeBlock {
+  /// Generates the Swift code for the ``CodeBlock``.
+  /// - Returns: The generated Swift code as a string.
   public func generateCode() -> String {
     let statements: CodeBlockItemListSyntax
     if let list = self.syntax.as(CodeBlockItemListSyntax.self) {
diff --git a/Sources/SyntaxKit/CodeBlock.swift b/Sources/SyntaxKit/CodeBlock.swift
index 51e3455..2da3ecc 100644
--- a/Sources/SyntaxKit/CodeBlock.swift
+++ b/Sources/SyntaxKit/CodeBlock.swift
@@ -30,39 +30,52 @@
 import Foundation
 import SwiftSyntax
 
+/// A protocol for types that can be represented as a SwiftSyntax node.
 public protocol CodeBlock {
+  /// The SwiftSyntax representation of the code block.
   var syntax: SyntaxProtocol { get }
 }
 
+/// A protocol for types that can build a ``CodeBlock``.
 public protocol CodeBlockBuilder {
+  /// The type of ``CodeBlock`` that this builder creates.
   associatedtype Result: CodeBlock
+  /// Builds the ``CodeBlock``.
   func build() -> Result
 }
 
+/// A result builder for creating arrays of ``CodeBlock``s.
 @resultBuilder
 public struct CodeBlockBuilderResult {
+  /// Builds a block of ``CodeBlock``s.
   public static func buildBlock(_ components: CodeBlock...) -> [CodeBlock] {
     components
   }
 
+  /// Builds an optional ``CodeBlock``.
   public static func buildOptional(_ component: CodeBlock?) -> CodeBlock {
     component ?? EmptyCodeBlock()
   }
 
+  /// Builds a ``CodeBlock`` from an `if` statement.
   public static func buildEither(first: CodeBlock) -> CodeBlock {
     first
   }
 
+  /// Builds a ``CodeBlock`` from an `else` statement.
   public static func buildEither(second: CodeBlock) -> CodeBlock {
     second
   }
 
+  /// Builds an array of ``CodeBlock``s from a `for` loop.
   public static func buildArray(_ components: [CodeBlock]) -> [CodeBlock] {
     components
   }
 }
 
+/// An empty ``CodeBlock``.
 public struct EmptyCodeBlock: CodeBlock {
+  /// The syntax for an empty code block.
   public var syntax: SyntaxProtocol {
     StringSegmentSyntax(content: .unknown(""))
   }
diff --git a/Sources/SyntaxKit/CommentBuilderResult.swift b/Sources/SyntaxKit/CommentBuilderResult.swift
index e0550a5..609be94 100644
--- a/Sources/SyntaxKit/CommentBuilderResult.swift
+++ b/Sources/SyntaxKit/CommentBuilderResult.swift
@@ -27,15 +27,20 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
+/// A result builder for creating arrays of ``Line``s for comments.
 @resultBuilder
 public enum CommentBuilderResult {
+  /// Builds a block of ``Line``s.
   public static func buildBlock(_ components: Line...) -> [Line] { components }
 }
 
 // MARK: - Public DSL surface
 
 extension CodeBlock {
-  /// Attach comments to the current `CodeBlock`.
+  /// Attaches comments to the current ``CodeBlock``.
+  ///
+  /// The provided lines are injected as leading trivia to the declaration produced by this ``CodeBlock``.
+  ///
   /// Usage:
   /// ```swift
   /// Struct("MyStruct") { ... }
@@ -44,7 +49,8 @@ extension CodeBlock {
   ///       Line(.doc, "This is a documentation comment")
   ///   }
   /// ```
-  /// The provided lines are injected as leading trivia to the declaration produced by this `CodeBlock`.
+  /// - Parameter content: A ``CommentBuilderResult`` that provides the comment lines.
+  /// - Returns: A new ``CodeBlock`` with the comments attached.
   public func comment(@CommentBuilderResult _ content: () -> [Line]) -> CodeBlock {
     CommentedCodeBlock(base: self, lines: content())
   }
diff --git a/Sources/SyntaxKit/ComputedProperty.swift b/Sources/SyntaxKit/ComputedProperty.swift
index 4da7312..d78e040 100644
--- a/Sources/SyntaxKit/ComputedProperty.swift
+++ b/Sources/SyntaxKit/ComputedProperty.swift
@@ -29,11 +29,17 @@
 
 import SwiftSyntax
 
+/// A Swift `var` declaration with a computed value.
 public struct ComputedProperty: CodeBlock {
   private let name: String
   private let type: String
   private let body: [CodeBlock]
 
+  /// Creates a computed property declaration.
+  /// - Parameters:
+  ///   - name: The name of the property.
+  ///   - type: The type of the property.
+  ///   - content: A ``CodeBlockBuilder`` that provides the body of the getter.
   public init(_ name: String, type: String, @CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.name = name
     self.type = type
diff --git a/Sources/SyntaxKit/Default.swift b/Sources/SyntaxKit/Default.swift
index bfd10c4..470a7e9 100644
--- a/Sources/SyntaxKit/Default.swift
+++ b/Sources/SyntaxKit/Default.swift
@@ -29,8 +29,12 @@
 
 import SwiftSyntax
 
+/// A `default` case in a `switch` statement.
 public struct Default: CodeBlock {
   private let body: [CodeBlock]
+
+  /// Creates a `default` case for a `switch` statement.
+  /// - Parameter content: A ``CodeBlockBuilder`` that provides the body of the case.
   public init(@CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.body = content()
   }
diff --git a/Sources/SyntaxKit/Enum.swift b/Sources/SyntaxKit/Enum.swift
index 36f5917..170f78b 100644
--- a/Sources/SyntaxKit/Enum.swift
+++ b/Sources/SyntaxKit/Enum.swift
@@ -29,16 +29,24 @@
 
 import SwiftSyntax
 
+/// A Swift `enum` declaration.
 public struct Enum: CodeBlock {
   private let name: String
   private let members: [CodeBlock]
   private var inheritance: String?
 
+  /// Creates an `enum` declaration.
+  /// - Parameters:
+  ///   - name: The name of the enum.
+  ///   - content: A ``CodeBlockBuilder`` that provides the members of the enum.
   public init(_ name: String, @CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.name = name
     self.members = content()
   }
 
+  /// Sets the inheritance for the enum.
+  /// - Parameter type: The type to inherit from.
+  /// - Returns: A copy of the enum with the inheritance set.
   public func inherits(_ type: String) -> Self {
     var copy = self
     copy.inheritance = type
@@ -76,15 +84,21 @@ public struct Enum: CodeBlock {
   }
 }
 
+/// A Swift `case` declaration inside an `enum`.
 public struct EnumCase: CodeBlock {
   private let name: String
   private var value: String?
   private var intValue: Int?
 
+  /// Creates a `case` declaration.
+  /// - Parameter name: The name of the case.
   public init(_ name: String) {
     self.name = name
   }
 
+  /// Sets the raw value of the case to a string.
+  /// - Parameter value: The string value.
+  /// - Returns: A copy of the case with the raw value set.
   public func equals(_ value: String) -> Self {
     var copy = self
     copy.value = value
@@ -92,6 +106,9 @@ public struct EnumCase: CodeBlock {
     return copy
   }
 
+  /// Sets the raw value of the case to an integer.
+  /// - Parameter value: The integer value.
+  /// - Returns: A copy of the case with the raw value set.
   public func equals(_ value: Int) -> Self {
     var copy = self
     copy.value = nil
diff --git a/Sources/SyntaxKit/Function.swift b/Sources/SyntaxKit/Function.swift
index da829f2..bac906f 100644
--- a/Sources/SyntaxKit/Function.swift
+++ b/Sources/SyntaxKit/Function.swift
@@ -29,6 +29,7 @@
 
 import SwiftSyntax
 
+/// A Swift `func` declaration.
 public struct Function: CodeBlock {
   private let name: String
   private let parameters: [Parameter]
@@ -37,6 +38,11 @@ public struct Function: CodeBlock {
   private var isStatic: Bool = false
   private var isMutating: Bool = false
 
+  /// Creates a `func` declaration.
+  /// - Parameters:
+  ///   - name: The name of the function.
+  ///   - returnType: The return type of the function, if any.
+  ///   - content: A ``CodeBlockBuilder`` that provides the body of the function.
   public init(
     _ name: String, returns returnType: String? = nil,
     @CodeBlockBuilderResult _ content: () -> [CodeBlock]
@@ -47,6 +53,12 @@ public struct Function: CodeBlock {
     self.body = content()
   }
 
+  /// Creates a `func` declaration.
+  /// - Parameters:
+  ///   - name: The name of the function.
+  ///   - returnType: The return type of the function, if any.
+  ///   - params: A ``ParameterBuilder`` that provides the parameters of the function.
+  ///   - content: A ``CodeBlockBuilder`` that provides the body of the function.
   public init(
     _ name: String, returns returnType: String? = nil,
     @ParameterBuilderResult _ params: () -> [Parameter],
@@ -58,12 +70,16 @@ public struct Function: CodeBlock {
     self.body = content()
   }
 
+  /// Marks the function as `static`.
+  /// - Returns: A copy of the function marked as `static`.
   public func `static`() -> Self {
     var copy = self
     copy.isStatic = true
     return copy
   }
 
+  /// Marks the function as `mutating`.
+  /// - Returns: A copy of the function marked as `mutating`.
   public func mutating() -> Self {
     var copy = self
     copy.isMutating = true
diff --git a/Sources/SyntaxKit/Group.swift b/Sources/SyntaxKit/Group.swift
index 6d56817..7b3e824 100644
--- a/Sources/SyntaxKit/Group.swift
+++ b/Sources/SyntaxKit/Group.swift
@@ -29,9 +29,12 @@
 
 import SwiftSyntax
 
+/// A group of code blocks.
 public struct Group: CodeBlock {
   let members: [CodeBlock]
 
+  /// Creates a group of code blocks.
+  /// - Parameter content: A ``CodeBlockBuilder`` that provides the members of the group.
   public init(@CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.members = content()
   }
diff --git a/Sources/SyntaxKit/If.swift b/Sources/SyntaxKit/If.swift
index 5935920..53e7bd5 100644
--- a/Sources/SyntaxKit/If.swift
+++ b/Sources/SyntaxKit/If.swift
@@ -29,11 +29,17 @@
 
 import SwiftSyntax
 
+/// An `if` statement.
 public struct If: CodeBlock {
   private let condition: CodeBlock
   private let body: [CodeBlock]
   private let elseBody: [CodeBlock]?
 
+  /// Creates an `if` statement.
+  /// - Parameters:
+  ///   - condition: The condition to evaluate. This can be a ``Let`` for optional binding.
+  ///   - then: A ``CodeBlockBuilder`` that provides the body of the `if` block.
+  ///   - elseBody: A ``CodeBlockBuilder`` that provides the body of the `else` block, if any.
   public init(
     _ condition: CodeBlock, @CodeBlockBuilderResult then: () -> [CodeBlock],
     else elseBody: (() -> [CodeBlock])? = nil
diff --git a/Sources/SyntaxKit/Init.swift b/Sources/SyntaxKit/Init.swift
index 3206de0..c94a9e8 100644
--- a/Sources/SyntaxKit/Init.swift
+++ b/Sources/SyntaxKit/Init.swift
@@ -29,9 +29,15 @@
 
 import SwiftSyntax
 
+/// An initializer expression.
 public struct Init: CodeBlock {
   private let type: String
   private let parameters: [Parameter]
+
+  /// Creates an initializer expression.
+  /// - Parameters:
+  ///   - type: The type to initialize.
+  ///   - params: A ``ParameterBuilder`` that provides the parameters for the initializer.
   public init(_ type: String, @ParameterBuilderResult _ params: () -> [Parameter]) {
     self.type = type
     self.parameters = params()
diff --git a/Sources/SyntaxKit/Let.swift b/Sources/SyntaxKit/Let.swift
index 5e4f53d..cd2d46d 100644
--- a/Sources/SyntaxKit/Let.swift
+++ b/Sources/SyntaxKit/Let.swift
@@ -29,9 +29,15 @@
 
 import SwiftSyntax
 
+/// A Swift `let` declaration for use in an `if` statement.
 public struct Let: CodeBlock {
   let name: String
   let value: String
+
+  /// Creates a `let` declaration for an `if` statement.
+  /// - Parameters:
+  ///   - name: The name of the constant.
+  ///   - value: The value to assign to the constant.
   public init(_ name: String, _ value: String) {
     self.name = name
     self.value = value
diff --git a/Sources/SyntaxKit/Line.swift b/Sources/SyntaxKit/Line.swift
index 8389e13..3017ae6 100644
--- a/Sources/SyntaxKit/Line.swift
+++ b/Sources/SyntaxKit/Line.swift
@@ -29,8 +29,9 @@
 
 import SwiftSyntax
 
-/// Represents a single comment line that can be attached to a syntax node when using `.comment { ... }` in the DSL.
+/// Represents a single comment line that can be attached to a syntax node.
 public struct Line {
+  /// The kind of comment line.
   public enum Kind {
     /// Regular line comment that starts with `//`.
     case line
@@ -38,10 +39,13 @@ public struct Line {
     case doc
   }
 
+  /// The kind of comment.
   public let kind: Kind
+  /// The text of the comment.
   public let text: String?
 
-  /// Convenience initializer for a regular line comment without specifying the kind explicitly.
+  /// Creates a regular line comment.
+  /// - Parameter text: The text of the comment.
   public init(_ text: String) {
     self.kind = .line
     self.text = text
@@ -55,6 +59,9 @@ public struct Line {
   /// Line(.doc, "Represents a model")    // documentation comment
   /// Line(.doc)                           // empty `///` line
   /// ```
+  /// - Parameters:
+  ///   - kind: The kind of comment. Defaults to `.line`.
+  ///   - text: The text of the comment. Defaults to `nil`.
   public init(_ kind: Kind = .line, _ text: String? = nil) {
     self.kind = kind
     self.text = text
diff --git a/Sources/SyntaxKit/Literal.swift b/Sources/SyntaxKit/Literal.swift
index 9d991b3..7e0e1dd 100644
--- a/Sources/SyntaxKit/Literal.swift
+++ b/Sources/SyntaxKit/Literal.swift
@@ -29,11 +29,17 @@
 
 import SwiftSyntax
 
+/// A literal value.
 public enum Literal: CodeBlock {
+  /// A string literal.
   case string(String)
+  /// A floating-point literal.
   case float(Double)
+  /// An integer literal.
   case integer(Int)
+  /// A `nil` literal.
   case `nil`
+  /// A boolean literal.
   case boolean(Bool)
 
   public var syntax: SyntaxProtocol {
diff --git a/Sources/SyntaxKit/Parameter.swift b/Sources/SyntaxKit/Parameter.swift
index 7aae1fb..08c76d9 100644
--- a/Sources/SyntaxKit/Parameter.swift
+++ b/Sources/SyntaxKit/Parameter.swift
@@ -31,12 +31,19 @@ import Foundation
 import SwiftParser
 import SwiftSyntax
 
+/// A parameter for a function or initializer.
 public struct Parameter: CodeBlock {
   let name: String
   let type: String
   let defaultValue: String?
   let isUnnamed: Bool
 
+  /// Creates a parameter for a function or initializer.
+  /// - Parameters:
+  ///   - name: The name of the parameter.
+  ///   - type: The type of the parameter.
+  ///   - defaultValue: The default value of the parameter, if any.
+  ///   - isUnnamed: A Boolean value that indicates whether the parameter is unnamed.
   public init(name: String, type: String, defaultValue: String? = nil, isUnnamed: Bool = false) {
     self.name = name
     self.type = type
diff --git a/Sources/SyntaxKit/ParameterBuilderResult.swift b/Sources/SyntaxKit/ParameterBuilderResult.swift
index 9f73803..3e3bad6 100644
--- a/Sources/SyntaxKit/ParameterBuilderResult.swift
+++ b/Sources/SyntaxKit/ParameterBuilderResult.swift
@@ -29,24 +29,30 @@
 
 import Foundation
 
+/// A result builder for creating arrays of ``Parameter``s.
 @resultBuilder
 public struct ParameterBuilderResult {
+  /// Builds a block of ``Parameter``s.
   public static func buildBlock(_ components: Parameter...) -> [Parameter] {
     components
   }
 
+  /// Builds an optional ``Parameter``.
   public static func buildOptional(_ component: Parameter?) -> [Parameter] {
     component.map { [$0] } ?? []
   }
 
+  /// Builds a ``Parameter`` from an `if` statement.
   public static func buildEither(first: Parameter) -> [Parameter] {
     [first]
   }
 
+  /// Builds a ``Parameter`` from an `else` statement.
   public static func buildEither(second: Parameter) -> [Parameter] {
     [second]
   }
 
+  /// Builds an array of ``Parameter``s from a `for` loop.
   public static func buildArray(_ components: [Parameter]) -> [Parameter] {
     components
   }
diff --git a/Sources/SyntaxKit/ParameterExp.swift b/Sources/SyntaxKit/ParameterExp.swift
index a8065a7..02274e8 100644
--- a/Sources/SyntaxKit/ParameterExp.swift
+++ b/Sources/SyntaxKit/ParameterExp.swift
@@ -29,10 +29,15 @@
 
 import SwiftSyntax
 
+/// A parameter for a function call.
 public struct ParameterExp: CodeBlock {
   let name: String
   let value: String
 
+  /// Creates a parameter for a function call.
+  /// - Parameters:
+  ///   - name: The name of the parameter.
+  ///   - value: The value of the parameter.
   public init(name: String, value: String) {
     self.name = name
     self.value = value
diff --git a/Sources/SyntaxKit/ParameterExpBuilderResult.swift b/Sources/SyntaxKit/ParameterExpBuilderResult.swift
index 8899213..4cf937a 100644
--- a/Sources/SyntaxKit/ParameterExpBuilderResult.swift
+++ b/Sources/SyntaxKit/ParameterExpBuilderResult.swift
@@ -29,24 +29,30 @@
 
 import Foundation
 
+/// A result builder for creating arrays of ``ParameterExp``s.
 @resultBuilder
 public struct ParameterExpBuilderResult {
+  /// Builds a block of ``ParameterExp``s.
   public static func buildBlock(_ components: ParameterExp...) -> [ParameterExp] {
     components
   }
 
+  /// Builds an optional ``ParameterExp``.
   public static func buildOptional(_ component: ParameterExp?) -> [ParameterExp] {
     component.map { [$0] } ?? []
   }
 
+  /// Builds a ``ParameterExp`` from an `if` statement.
   public static func buildEither(first: ParameterExp) -> [ParameterExp] {
     [first]
   }
 
+  /// Builds a ``ParameterExp`` from an `else` statement.
   public static func buildEither(second: ParameterExp) -> [ParameterExp] {
     [second]
   }
 
+  /// Builds an array of ``ParameterExp``s from a `for` loop.
   public static func buildArray(_ components: [ParameterExp]) -> [ParameterExp] {
     components
   }
diff --git a/Sources/SyntaxKit/PlusAssign.swift b/Sources/SyntaxKit/PlusAssign.swift
index bf322d7..8b79cc8 100644
--- a/Sources/SyntaxKit/PlusAssign.swift
+++ b/Sources/SyntaxKit/PlusAssign.swift
@@ -29,10 +29,15 @@
 
 import SwiftSyntax
 
+/// A `+=` expression.
 public struct PlusAssign: CodeBlock {
   private let target: String
   private let value: String
 
+  /// Creates a `+=` expression.
+  /// - Parameters:
+  ///   - target: The variable to assign to.
+  ///   - value: The value to add and assign.
   public init(_ target: String, _ value: String) {
     self.target = target
     self.value = value
diff --git a/Sources/SyntaxKit/Return.swift b/Sources/SyntaxKit/Return.swift
index 6abfda7..78c05d4 100644
--- a/Sources/SyntaxKit/Return.swift
+++ b/Sources/SyntaxKit/Return.swift
@@ -29,8 +29,12 @@
 
 import SwiftSyntax
 
+/// A `return` statement.
 public struct Return: CodeBlock {
   private let exprs: [CodeBlock]
+
+  /// Creates a `return` statement.
+  /// - Parameter content: A ``CodeBlockBuilder`` that provides the expression to return.
   public init(@CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.exprs = content()
   }
diff --git a/Sources/SyntaxKit/Struct.swift b/Sources/SyntaxKit/Struct.swift
index 63c474d..50d6dc6 100644
--- a/Sources/SyntaxKit/Struct.swift
+++ b/Sources/SyntaxKit/Struct.swift
@@ -29,12 +29,18 @@
 
 import SwiftSyntax
 
+/// A Swift `struct` declaration.
 public struct Struct: CodeBlock {
   private let name: String
   private let members: [CodeBlock]
   private var inheritance: String?
   private var genericParameter: String?
 
+  /// Creates a `struct` declaration.
+  /// - Parameters:
+  ///   - name: The name of the struct.
+  ///   - generic: A generic parameter for the struct, if any.
+  ///   - content: A ``CodeBlockBuilder`` that provides the members of the struct.
   public init(
     _ name: String, generic: String? = nil, @CodeBlockBuilderResult _ content: () -> [CodeBlock]
   ) {
@@ -43,6 +49,9 @@ public struct Struct: CodeBlock {
     self.genericParameter = generic
   }
 
+  /// Sets the inheritance for the struct.
+  /// - Parameter type: The type to inherit from.
+  /// - Returns: A copy of the struct with the inheritance set.
   public func inherits(_ type: String) -> Self {
     var copy = self
     copy.inheritance = type
diff --git a/Sources/SyntaxKit/Switch.swift b/Sources/SyntaxKit/Switch.swift
index 9e306f3..b03f7fb 100644
--- a/Sources/SyntaxKit/Switch.swift
+++ b/Sources/SyntaxKit/Switch.swift
@@ -29,10 +29,15 @@
 
 import SwiftSyntax
 
+/// A `switch` statement.
 public struct Switch: CodeBlock {
   private let expression: String
   private let cases: [CodeBlock]
 
+  /// Creates a `switch` statement.
+  /// - Parameters:
+  ///   - expression: The expression to switch on.
+  ///   - content: A ``CodeBlockBuilder`` that provides the cases for the switch.
   public init(_ expression: String, @CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
     self.expression = expression
     self.cases = content()
diff --git a/Sources/SyntaxKit/SwitchCase.swift b/Sources/SyntaxKit/SwitchCase.swift
index a67ee68..1d219b4 100644
--- a/Sources/SyntaxKit/SwitchCase.swift
+++ b/Sources/SyntaxKit/SwitchCase.swift
@@ -29,10 +29,15 @@
 
 import SwiftSyntax
 
+/// A `case` in a `switch` statement.
 public struct SwitchCase: CodeBlock {
   private let patterns: [String]
   private let body: [CodeBlock]
 
+  /// Creates a `case` for a `switch` statement.
+  /// - Parameters:
+  ///   - patterns: The patterns to match for the case.
+  ///   - content: A ``CodeBlockBuilder`` that provides the body of the case.
   public init(_ patterns: String..., @CodeBlockBuilderResult content: () -> [CodeBlock]) {
     self.patterns = patterns
     self.body = content()
diff --git a/Sources/SyntaxKit/Trivia+Comments.swift b/Sources/SyntaxKit/Trivia+Comments.swift
index 04049be..ecc7008 100644
--- a/Sources/SyntaxKit/Trivia+Comments.swift
+++ b/Sources/SyntaxKit/Trivia+Comments.swift
@@ -30,7 +30,9 @@
 import SwiftSyntax
 
 extension Trivia {
-  /// Extract comment strings (line comments, doc comments, block comments) from the trivia collection.
+  /// Extracts comment strings from the trivia collection.
+  ///
+  /// This includes line comments, documentation comments, and block comments.
   public var comments: [String] {
     compactMap { piece in
       switch piece {
@@ -45,7 +47,7 @@ extension Trivia {
     }
   }
 
-  /// Indicates whether the trivia contains any comments.
+  /// A Boolean value that indicates whether the trivia contains any comments.
   public var hasComments: Bool {
     !comments.isEmpty
   }
diff --git a/Sources/SyntaxKit/Variable.swift b/Sources/SyntaxKit/Variable.swift
index 2cf0e87..b37ec0d 100644
--- a/Sources/SyntaxKit/Variable.swift
+++ b/Sources/SyntaxKit/Variable.swift
@@ -29,12 +29,19 @@
 
 import SwiftSyntax
 
+/// A Swift `let` or `var` declaration with an explicit type.
 public struct Variable: CodeBlock {
   private let kind: VariableKind
   private let name: String
   private let type: String
   private let defaultValue: String?
 
+  /// Creates a `let` or `var` declaration with an explicit type.
+  /// - Parameters:
+  ///   - kind: The kind of variable, either ``VariableKind/let`` or ``VariableKind/var``.
+  ///   - name: The name of the variable.
+  ///   - type: The type of the variable.
+  ///   - defaultValue: The initial value of the variable, if any.
   public init(_ kind: VariableKind, name: String, type: String, equals defaultValue: String? = nil)
   {
     self.kind = kind
diff --git a/Sources/SyntaxKit/VariableDecl.swift b/Sources/SyntaxKit/VariableDecl.swift
index 592a810..64da71b 100644
--- a/Sources/SyntaxKit/VariableDecl.swift
+++ b/Sources/SyntaxKit/VariableDecl.swift
@@ -29,11 +29,17 @@
 
 import SwiftSyntax
 
+/// A Swift `let` or `var` declaration.
 public struct VariableDecl: CodeBlock {
   private let kind: VariableKind
   private let name: String
   private let value: String?
 
+  /// Creates a `let` or `var` declaration.
+  /// - Parameters:
+  ///   - kind: The kind of variable, either ``VariableKind/let`` or ``VariableKind/var``.
+  ///   - name: The name of the variable.
+  ///   - value: The initial value of the variable, if any.
   public init(_ kind: VariableKind, name: String, equals value: String? = nil) {
     self.kind = kind
     self.name = name
diff --git a/Sources/SyntaxKit/VariableExp.swift b/Sources/SyntaxKit/VariableExp.swift
index c58a335..5616290 100644
--- a/Sources/SyntaxKit/VariableExp.swift
+++ b/Sources/SyntaxKit/VariableExp.swift
@@ -29,21 +29,35 @@
 
 import SwiftSyntax
 
+/// An expression that refers to a variable.
 public struct VariableExp: CodeBlock {
   let name: String
 
+  /// Creates a variable expression.
+  /// - Parameter name: The name of the variable.
   public init(_ name: String) {
     self.name = name
   }
 
+  /// Accesses a property on the variable.
+  /// - Parameter propertyName: The name of the property to access.
+  /// - Returns: A ``PropertyAccessExp`` that represents the property access.
   public func property(_ propertyName: String) -> CodeBlock {
     PropertyAccessExp(baseName: name, propertyName: propertyName)
   }
 
+  /// Calls a method on the variable.
+  /// - Parameter methodName: The name of the method to call.
+  /// - Returns: A ``FunctionCallExp`` that represents the method call.
   public func call(_ methodName: String) -> CodeBlock {
     FunctionCallExp(baseName: name, methodName: methodName)
   }
 
+  /// Calls a method on the variable with parameters.
+  /// - Parameters:
+  ///  - methodName: The name of the method to call.
+  ///  - params: A ``ParameterExpBuilder`` that provides the parameters for the method call.
+  /// - Returns: A ``FunctionCallExp`` that represents the method call.
   public func call(_ methodName: String, @ParameterExpBuilderResult _ params: () -> [ParameterExp])
     -> CodeBlock
   {
@@ -55,10 +69,15 @@ public struct VariableExp: CodeBlock {
   }
 }
 
+/// An expression that accesses a property on a base expression.
 public struct PropertyAccessExp: CodeBlock {
   let baseName: String
   let propertyName: String
 
+  /// Creates a property access expression.
+  /// - Parameters:
+  ///  - baseName: The name of the base variable.
+  ///  - propertyName: The name of the property to access.
   public init(baseName: String, propertyName: String) {
     self.baseName = baseName
     self.propertyName = propertyName
@@ -76,17 +95,27 @@ public struct PropertyAccessExp: CodeBlock {
   }
 }
 
+/// An expression that calls a function.
 public struct FunctionCallExp: CodeBlock {
   let baseName: String
   let methodName: String
   let parameters: [ParameterExp]
 
+  /// Creates a function call expression.
+  /// - Parameters:
+  ///   - baseName: The name of the base variable.
+  ///   - methodName: The name of the method to call.
   public init(baseName: String, methodName: String) {
     self.baseName = baseName
     self.methodName = methodName
     self.parameters = []
   }
 
+  /// Creates a function call expression with parameters.
+  /// - Parameters:
+  ///  - baseName: The name of the base variable.
+  ///  - methodName: The name of the method to call.
+  ///  - parameters: The parameters for the method call.
   public init(baseName: String, methodName: String, parameters: [ParameterExp]) {
     self.baseName = baseName
     self.methodName = methodName
diff --git a/Sources/SyntaxKit/VariableKind.swift b/Sources/SyntaxKit/VariableKind.swift
index 8eecaca..a81a0f6 100644
--- a/Sources/SyntaxKit/VariableKind.swift
+++ b/Sources/SyntaxKit/VariableKind.swift
@@ -29,7 +29,10 @@
 
 import Foundation
 
+/// The kind of a variable declaration.
 public enum VariableKind {
+  /// A `let` declaration.
   case `let`
+  /// A `var` declaration.
   case `var`
 }

From 4274243f1fae2d9c1081c95199f51abfd5e81fd4 Mon Sep 17 00:00:00 2001
From: leogdion <leogdion@brightdigit.com>
Date: Tue, 17 Jun 2025 09:55:42 -0400
Subject: [PATCH 3/3] fixing wording

---
 .../Documentation.docc/Documentation.md       | 69 ++++++++++---------
 1 file changed, 35 insertions(+), 34 deletions(-)

diff --git a/Sources/SyntaxKit/Documentation.docc/Documentation.md b/Sources/SyntaxKit/Documentation.docc/Documentation.md
index 24431e9..091cbee 100644
--- a/Sources/SyntaxKit/Documentation.docc/Documentation.md
+++ b/Sources/SyntaxKit/Documentation.docc/Documentation.md
@@ -1,10 +1,10 @@
 # ``SyntaxKit``
 
-SyntaxKit is a Swift package that allows developers to build Swift code using result builders. It provides a declarative way to generate Swift code structures using SwiftSyntax.
+SyntaxKit provides a declarative way to generate Swift code structures using SwiftSyntax.
 
 ## Overview
 
-SyntaxKit provides a set of result builders that allow you to create Swift code structures in a declarative way. Here's an example:
+SyntaxKit allows developers to build Swift code using result builders which enable the creation of Swift code structures in a declarative way. Here's an example:
 
 ```swift
 import SyntaxKit
@@ -37,37 +37,6 @@ struct BlackjackCard {
 }
 ```
 
-## Topics
-
-### Declarations
-
-- ``Struct``
-- ``Enum``
-- ``EnumCase``
-- ``Function``
-- ``Init``
-- ``ComputedProperty``
-- ``VariableDecl``
-- ``Let``
-- ``Variable``
-
-### Expressions & Statements
-- ``Assignment``
-- ``PlusAssign``
-- ``Return``
-- ``VariableExp``
-
-### Control Flow
-- ``If``
-- ``Switch``
-- ``SwitchCase``
-- ``Default``
-
-### Building Blocks
-- ``CodeBlock``
-- ``Parameter``
-- ``Literal``
-
 ## Full Example
 
 Here is a more comprehensive example that demonstrates many of SyntaxKit's features to generate a `BlackjackCard` struct.
@@ -214,4 +183,36 @@ struct BlackjackCard {
     return output
   }
 }
-```
\ No newline at end of file
+```
+
+## Topics
+
+### Declarations
+
+- ``Struct``
+- ``Enum``
+- ``EnumCase``
+- ``Function``
+- ``Init``
+- ``ComputedProperty``
+- ``VariableDecl``
+- ``Let``
+- ``Variable``
+
+### Expressions & Statements
+- ``Assignment``
+- ``PlusAssign``
+- ``Return``
+- ``VariableExp``
+
+### Control Flow
+- ``If``
+- ``Switch``
+- ``SwitchCase``
+- ``Default``
+
+### Building Blocks
+- ``CodeBlock``
+- ``Parameter``
+- ``Literal``
+