Add documentation to all not-yet-documented symbols

Author: stackotter

Sources/MacroToolkit/Destructuring.swift

@@ -1,4 +1,5 @@
 // TODO: Figure out a destructuring implementation that uses variadic generics (tricky without same type requirements)
+/// Destructures the given `elements` into a tuple of 0 elements if there are exactly 0 elements.
 public func destructure<Element>(_ elements: some Sequence<Element>) -> ()? {
     let array = Array(elements)
     guard array.count == 0 else {
@@ -8,6 +9,7 @@ public func destructure<Element>(_ elements: some Sequence<Element>) -> ()? {
 }
 
 /// Destructures the given `elements` into a single element if there is exactly one element.
+///
 /// Named differently to allow type inference to still work correctly (single element tuples
 /// are weird in Swift).
 public func destructureSingle<Element>(_ elements: some Sequence<Element>) -> (Element)? {
@@ -70,12 +72,15 @@ public func destructure<Element>(_ elements: some Sequence<Element>) -> (
     return (array[0], array[1], array[2], array[3], array[4], array[5])
 }
 
+/// Destructures the given `type` into a name and a tuple of 0 generic type parameters if there are exactly 0 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, ())? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a name and 1 generic type parameter if there is exactly 1 generic type parameter.
+///
 /// Named differently to allow type inference to still work correctly (single element tuples
 /// are weird in Swift).
 public func destructureSingle(_ type: SimpleType) -> (String, (Type))? {
@@ -84,42 +89,50 @@ public func destructureSingle(_ type: SimpleType) -> (String, (Type))? {
     }
 }
 
+/// Destructures the given `type` into a name and a tuple of 2 generic type parameters if there are exactly 2 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, (Type, Type))? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a name and a tuple of 3 generic type parameters if there are exactly 3 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, (Type, Type, Type))? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a name and a tuple of 4 generic type parameters if there are exactly 4 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, (Type, Type, Type, Type))? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a name and a tuple of 5 generic type parameters if there are exactly 5 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, (Type, Type, Type, Type, Type))? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a name and a tuple of 6 generic type parameters if there are exactly 6 generic type parameters.
 public func destructure(_ type: SimpleType) -> (String, (Type, Type, Type, Type, Type, Type))? {
     destructure(type.genericArguments ?? []).map { arguments in
         (type.name, arguments)
     }
 }
 
+/// Destructures the given `type` into a tuple of 0 parameter types and a return type if there are exactly 0 parameters.
 public func destructure(_ type: FunctionType) -> ((), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a parameter type and a return type if there is exactly 1 parameter.
+///
 /// Named differently to allow type inference to still work correctly (single element tuples
 /// are weird in Swift).
 public func destructureSingle(_ type: FunctionType) -> ((Type), Type)? {
@@ -128,36 +141,42 @@ public func destructureSingle(_ type: FunctionType) -> ((Type), Type)? {
     }
 }
 
+/// Destructures the given `type` into a tuple of 2 parameter types and a return type if there are exactly 2 parameters.
 public func destructure(_ type: FunctionType) -> ((Type, Type), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a tuple of 3 parameter types and a return type if there are exactly 3 parameters.
 public func destructure(_ type: FunctionType) -> ((Type, Type, Type), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a tuple of 4 parameter types and a return type if there are exactly 4 parameters.
 public func destructure(_ type: FunctionType) -> ((Type, Type, Type, Type), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a tuple of 5 parameter types and a return type if there are exactly 5 parameters.
 public func destructure(_ type: FunctionType) -> ((Type, Type, Type, Type, Type), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a tuple of 6 parameter types and a return type if there are exactly 6 parameters.
 public func destructure(_ type: FunctionType) -> ((Type, Type, Type, Type, Type, Type), Type)? {
     destructure(type.parameters).map { parameters in
         (parameters, type.returnType)
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<()>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
@@ -172,6 +191,8 @@ public func destructure(_ type: Type) -> DestructuredType<()>? {
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
+///
 /// Named differently to allow type inference to still work correctly (single element tuples
 /// are weird in Swift).
 public func destructureSingle(_ type: Type) -> DestructuredType<(Type)>? {
@@ -188,6 +209,7 @@ public func destructureSingle(_ type: Type) -> DestructuredType<(Type)>? {
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
@@ -202,6 +224,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type)>? {
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
@@ -216,6 +239,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type)>? {
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
@@ -230,6 +254,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Typ
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
@@ -244,6 +269,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Typ
     }
 }
 
+/// Destructures the given `type` into a ``DestructuredType`` for easy pattern matching.
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in

Sources/MacroToolkit/Diagnostics.swift

@@ -1,13 +1,18 @@
-import SwiftSyntax
-import SwiftDiagnostics
 import Foundation
+import SwiftDiagnostics
+import SwiftSyntax
 
 // Taken from: https://github.com/DougGregor/swift-macro-examples/blob/f61ac7cdca8dc3557e53f86e7e03df1353908d3e/MacroExamplesPlugin/Diagnostics.swift
+/// A simple diagnostic with a message, id, and severity.
 public struct SimpleDiagnosticMessage: DiagnosticMessage, Error {
+    /// The human-readable message.
     public let message: String
+    /// The unique diagnostic id (should be the same for all diagnostics produced by the same codepath).
     public let diagnosticID: MessageID
+    /// The diagnostic's severity.
     public let severity: DiagnosticSeverity
 
+    /// Creates a new diagnostic message.
     public init(message: String, diagnosticID: MessageID, severity: DiagnosticSeverity) {
         self.message = message
         self.diagnosticID = diagnosticID
@@ -16,6 +21,7 @@ public struct SimpleDiagnosticMessage: DiagnosticMessage, Error {
 }
 
 extension SimpleDiagnosticMessage: FixItMessage {
+    /// The unique fix-it id (should be the same for all fix-its produced by the same codepath).
     public var fixItID: MessageID { diagnosticID }
 }
 
@@ -34,44 +40,57 @@ public struct MacroError: LocalizedError {
     }
 }
 
+/// A way to create rich diagnostics with no unnecessary boilerplate code. Only provide the
+/// important details and the rest will be given sensible defaults.
 public struct DiagnosticBuilder {
+    /// The node that the diagnostic will be attached to.
     var node: Syntax
+    /// The message that the diagnostic will show.
     var message: String?
+    /// The diagnostic id (should be the same for all diagnostics produced by the same codepath).
     var messageID = MessageID(domain: "UnknownDomain", id: "UnknownError")
+    /// The fix-its that will be associated with the diagnostics.
     var fixIts: [FixIt] = []
+    /// The additional syntax nodes that will be highlighted by the diagnostic.
     var highlights: [Syntax] = []
 
     /// Defaults to ``DiagnosticSeverity/error``.
     var severity: DiagnosticSeverity = .error
 
+    /// Creates a new builder for a diagnostics related to the given `node`.
     public init(for node: some SyntaxProtocol) {
         self.node = Syntax(node)
     }
 
+    /// Set the message.
     public func message(_ message: String) -> Self {
         var builder = self
         builder.message = message
         return builder
     }
 
+    /// Set the severity.
     public func severity(_ severity: DiagnosticSeverity) -> Self {
         var builder = self
         builder.severity = severity
         return builder
     }
 
+    /// Set the message id.
     public func messageID(_ messageID: MessageID) -> Self {
         var builder = self
         builder.messageID = messageID
         return builder
     }
 
+    /// Add a fix-it suggestion.
     public func fixIt(_ fixIt: FixIt) -> Self {
         var builder = self
         builder.fixIts.append(fixIt)
         return builder
     }
 
+    /// Highlight a syntax node related to the diagnostic.
     public func highlight(_ node: some SyntaxProtocol) -> Self {
         var builder = self
         builder.highlights.append(Syntax(node))
@@ -88,25 +107,29 @@ public struct DiagnosticBuilder {
         old: some SyntaxProtocol,
         new: some SyntaxProtocol
     ) -> Self {
-        fixIt(FixIt(
-            message: SimpleDiagnosticMessage(
-                message: message ?? "suggested replacement",
-                diagnosticID: messageID ?? self.messageID,
-                severity: .error
-            ),
-            changes: [
-                FixIt.Change.replace(
-                    oldNode: Syntax(old),
-                    newNode: Syntax(new)
-                )
-            ]
-        ))
+        fixIt(
+            FixIt(
+                message: SimpleDiagnosticMessage(
+                    message: message ?? "suggested replacement",
+                    diagnosticID: messageID ?? self.messageID,
+                    severity: .error
+                ),
+                changes: [
+                    FixIt.Change.replace(
+                        oldNode: Syntax(old),
+                        newNode: Syntax(new)
+                    )
+                ]
+            ))
     }
 
+    /// Set the message id (shorthand for ``messageID(_:)``).
     public func messageID(domain: String, id: String) -> Self {
         messageID(MessageID(domain: domain, id: id))
     }
 
+    /// Build the final diagnostic to be emitted. Defaults will be used for any
+    /// unset configuration values.
     public func build() -> Diagnostic {
         let messageID = messageID
         return Diagnostic(
@@ -120,4 +143,4 @@ public struct DiagnosticBuilder {
             fixIts: fixIts
         )
     }
-}
+}

Sources/MacroToolkit/Expr.swift

@@ -1,36 +1,41 @@
 import SwiftSyntax
 
+/// Wraps an expression syntax node.
 public struct Expr {
+    /// The underlying syntax node.
     public var _syntax: ExprSyntax
 
-    public init(_ syntax: ExprSyntax) {
-        _syntax = syntax
-    }
-
+    /// Wraps a syntax node.
     public init(_ syntax: any ExprSyntaxProtocol) {
         _syntax = ExprSyntax(syntax)
     }
 
+    /// Attempts to get the expression as a string literal.
     public var asStringLiteral: StringLiteral? {
         StringLiteral(self._syntax)
     }
 
+    /// Attempts to get the expression as a boolean literal.
     public var asBooleanLiteral: BooleanLiteral? {
         BooleanLiteral(self._syntax)
     }
 
+    /// Attempts to get the expression as a floating point literal.
     public var asFloatLiteral: FloatLiteral? {
         FloatLiteral(self._syntax)
     }
 
+    /// Attempts to get the expression as an integer literal.
     public var asIntegerLiteral: IntegerLiteral? {
         IntegerLiteral(self._syntax)
     }
 
+    /// Attempts to get the expression as a nil literal.
     public var asNilLiteral: NilLiteral? {
         NilLiteral(self._syntax)
     }
 
+    /// Attempts to get the expression as a regex literal.
     public var asRegexLiteral: RegexLiteral? {
         RegexLiteral(self._syntax)
     }

Sources/MacroToolkit/ExprProtocol.swift

@@ -1,19 +1,27 @@
 import SwiftSyntax
 
+/// A protocol for expression syntax wrappers to conform to. Allows simple conversion between expression wrappers.
 public protocol ExprProtocol {
+    /// The type of the underlying syntax node being wrapped.
     associatedtype WrappedSyntax: ExprSyntaxProtocol
+    /// The underlying syntax node being wrapped.
     var _syntax: WrappedSyntax { get }
+    /// Wraps a syntax node.
     init(_ syntax: WrappedSyntax)
 }
 
 extension ExprProtocol {
+    /// Attempts to initialize the wrapper from an arbitrary expression (succeeds
+    /// if the expression is the right type of syntax).
     public init?(_ syntax: ExprSyntaxProtocol) {
         guard let syntax = syntax.as(WrappedSyntax.self) else {
             return nil
         }
         self.init(syntax)
     }
 
+    /// Attempts to initialize the wrapper from an arbitrary expression (succeeds
+    /// if the expression is the right type of syntax).
     public init?(_ expr: Expr) {
         guard let syntax = expr._syntax.as(WrappedSyntax.self) else {
             return nil