Create documentation homepage with symbols sorted into sensible categories and document more symbols

Author: stackotter

Package.resolved

@@ -1,5 +1,23 @@
 {
   "pins" : [
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",

Package.swift

@@ -1,7 +1,7 @@
 // swift-tools-version: 5.9
 
-import PackageDescription
 import CompilerPluginSupport
+import PackageDescription
 
 let package = Package(
     name: "swift-macro-toolkit",
@@ -10,10 +10,13 @@ let package = Package(
         .library(
             name: "MacroToolkit",
             targets: ["MacroToolkit"]
-        ),
+        )
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-syntax.git", from: "509.0.0-swift-5.9-DEVELOPMENT-SNAPSHOT-2023-04-25-b"),
+        .package(
+            url: "https://github.com/apple/swift-syntax.git",
+            from: "509.0.0-swift-5.9-DEVELOPMENT-SNAPSHOT-2023-04-25-b"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
     ],
     targets: [
         // Implementations of macros tested by tests
@@ -22,7 +25,7 @@ let package = Package(
             dependencies: [
                 .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
                 .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
-                "MacroToolkit"
+                "MacroToolkit",
             ]
         ),
 
@@ -33,7 +36,7 @@ let package = Package(
             name: "MacroToolkit",
             dependencies: [
                 .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
-                .product(name: "SwiftCompilerPlugin", package: "swift-syntax")
+                .product(name: "SwiftCompilerPlugin", package: "swift-syntax"),
             ]
         ),
 

README.md

@@ -115,9 +115,7 @@ return literal.value
 #### With Macro Toolkit
 
 ```swift
-guard
-    case let .nominal("Result", (successType, failureType))? = destructure(returnType)
-else {
+guard case let .simple("Result", (successType, failureType))? = destructure(returnType) else {
     throw MacroError("Invalid return type")
 }
 ```
@@ -126,9 +124,9 @@ else {
 
 ```swift
 guard
-    let nominalReturnType = returnType.as(SimpleTypeIdentifierSyntax.self),
-    nominalReturnType.name.description == "Result",
-    let genericArguments = (nominalReturnType.genericArgumentClause?.arguments).map(Array.init),
+    let simpleReturnType = returnType.as(SimpleTypeIdentifierSyntax.self),
+    simpleReturnType.name.description == "Result",
+    let genericArguments = (simpleReturnType.genericArgumentClause?.arguments).map(Array.init),
     genericArguments.count == 2
 else {
     throw MacroError("Invalid return type")
@@ -165,8 +163,8 @@ func returnsVoid(_ function: FunctionDeclSyntax) -> Bool {
         }
 
         if let element = tuple.elements.first, tuple.elements.count == 1 {
-            let isLabeled = element.name == nil && element.secondName == nil
-            return isLabeled && isVoid(TypeSyntax(element.type))
+            let isUnlabeled = element.name == nil && element.secondName == nil
+            return isUnlabeled && isVoid(TypeSyntax(element.type))
         }
         return false
     }

Sources/MacroToolkit/Attribute.swift

@@ -12,20 +12,24 @@ public struct Attribute {
 
     /// Creates a new attribute with the given name.
     public init(named name: String) {
-        _syntax = AttributeSyntax(attributeName: SimpleTypeIdentifierSyntax(
-            name: .identifier("DictionaryStorage")
-        ))
+        _syntax = AttributeSyntax(
+            attributeName: SimpleTypeIdentifierSyntax(
+                name: .identifier("DictionaryStorage")
+            )
+        )
     }
 
     /// The attribute's name.
     public var name: SimpleType {
         guard let type = SimpleType(_syntax.attributeName) else {
-            fatalError("Assumed that attribute name would be simple type, but got: \(_syntax.attributeName)")
+            fatalError(
+                "Assumed that attribute name would be simple type, but got: \(_syntax.attributeName)"
+            )
         }
         return type
     }
 
-    /// 
+    /// Attempts to get the attribute as a macro attribute (e.g. `@MyMacro` as opposed to `@propertyWrapper`).
     public var asMacroAttribute: MacroAttribute? {
         MacroAttribute(_syntax)
     }

Sources/MacroToolkit/AttributeListElement.swift

@@ -6,6 +6,7 @@ public enum AttributeListElement {
     case attribute(Attribute)
     case conditionalCompilationBlock(ConditionalCompilationBlock)
 
+    /// The underlying attribute (if any).
     public var attribute: Attribute? {
         switch self {
             case .attribute(let attribute):
@@ -15,6 +16,8 @@ public enum AttributeListElement {
         }
     }
 
+    /// The underlying conditional compilation block (e.g.
+    /// `#if ... \n @propertyWrapper \n #endif`).
     public var conditionalCompilationBlock: ConditionalCompilationBlock? {
         switch self {
             case .conditionalCompilationBlock(let conditionalCompilationBlock):
@@ -36,13 +39,16 @@ extension Sequence where Element == AttributeListElement {
                 case .attribute(let attribute):
                     element = .attribute(attribute._syntax.with(\.trailingTrivia, [.spaces(1)]))
                 case .conditionalCompilationBlock(let conditionalCompilationBlock):
-                    element = .ifConfigDecl(conditionalCompilationBlock._syntax.with(\.trailingTrivia, [.spaces(1)]))
+                    element = .ifConfigDecl(
+                        conditionalCompilationBlock._syntax.with(\.trailingTrivia, [.spaces(1)]))
             }
             list = list.appending(element)
         }
         return list
     }
 
+    /// Gets the first attribute with the given `name`. The name doesn't include
+    /// any generic parameters (see ``Attribute/name``).
     public func first(called name: String) -> Attribute? {
         // TODO: How should conditional compilation attributes be handled?
         compactMap(\.attribute).first { attribute in

Sources/MacroToolkit/BooleanLiteral.swift

@@ -1,13 +1,15 @@
 import SwiftSyntax
 
+/// Wraps a boolean literal (i.e. `true` or `false`).
 public struct BooleanLiteral: LiteralProtocol {
     public var _syntax: BooleanLiteralExprSyntax
 
+    /// Wraps a boolean literal syntax node.
     public init(_ syntax: BooleanLiteralExprSyntax) {
         _syntax = syntax
     }
 
     public var value: Bool {
         _syntax.booleanLiteral.tokenKind == .keyword(.true)
-    }    
+    }
 }

Sources/MacroToolkit/ConditionalCompilationBlock.swift

@@ -1,9 +1,11 @@
 import SwiftSyntax
 
-/// A compile-time conditional block (i.e. `#if ...`).
+/// A compile-time conditional block (i.e. `#if ... \n ... \n #endif`).
 public struct ConditionalCompilationBlock {
+    /// The underlying syntax node.
     public var _syntax: IfConfigDeclSyntax
 
+    /// Wraps a compile-time conditional block syntax node.
     public init(_ syntax: IfConfigDeclSyntax) {
         _syntax = syntax
     }

Sources/MacroToolkit/Decl.swift

@@ -1,25 +1,27 @@
 import SwiftSyntax
 
+/// A declaration (e.g. an `enum` or a `struct` etc.).
 public struct Decl {
+    /// The underlying syntax node for the declaration.
     public var _syntax: DeclSyntax
 
-    public init(_ syntax: DeclSyntax) {
-        _syntax = syntax
-    }
-
+    /// Wraps a declaration syntax node.
     public init(_ syntax: any DeclSyntaxProtocol) {
         _syntax = DeclSyntax(syntax)
     }
 
-    // TODO: Add conversions for all possible member types
+    // TODO: Add conversions for all possible member types. Maybe make this into an enum like ``Type``
+    /// Attempts to get the declaration as an enum.
     public var asEnum: Enum? {
         _syntax.as(EnumDeclSyntax.self).map(Enum.init)
     }
 
+    /// Attempts to get the declaration as a struct.
     public var asStruct: Struct? {
         _syntax.as(StructDeclSyntax.self).map(Struct.init)
     }
 
+    /// Attempts to get the declaration as a variable.
     public var asVariable: Variable? {
         _syntax.as(VariableDeclSyntax.self).map(Variable.init)
     }

Sources/MacroToolkit/DeclGroup.swift

@@ -1,16 +1,22 @@
 import SwiftSyntax
 
+/// Wraps a declaration group (a declaration with a scoped block of members).
+/// For example an `enum` or a `struct` etc.
 public struct DeclGroup {
+    /// The underlying syntax node.
     public var _syntax: DeclGroupSyntax
 
+    /// Wraps a declaration group syntax node.
     public init(_ syntax: DeclGroupSyntax) {
         _syntax = syntax
     }
 
+    /// Gets whether the declaration has the `public` access modifier.
     public var isPublic: Bool {
         _syntax.isPublic
     }
 
+    /// Gets all of the declaration group's member declarations.
     public var members: [Decl] {
         _syntax.memberBlock.members.map(\.decl).map(Decl.init)
     }

Sources/MacroToolkit/Destructuring.swift

@@ -7,6 +7,7 @@ public func destructure<Element>(_ elements: some Sequence<Element>) -> ()? {
     return ()
 }
 
+/// 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)? {
@@ -17,6 +18,7 @@ public func destructureSingle<Element>(_ elements: some Sequence<Element>) -> (E
     return (array[0])
 }
 
+/// Destructures the given `elements` into a tuple of 2 elements if there are exactly 2 elements.
 public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element)? {
     let array = Array(elements)
     guard array.count == 2 else {
@@ -25,31 +27,42 @@ public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element
     return (array[0], array[1])
 }
 
-public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element, Element)? {
+/// Destructures the given `elements` into a tuple of 3 elements if there are exactly 3 elements.
+public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element, Element)?
+{
     let array = Array(elements)
     guard array.count == 3 else {
         return nil
     }
     return (array[0], array[1], array[2])
 }
 
-public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element, Element, Element)? {
+/// Destructures the given `elements` into a tuple of 4 elements if there are exactly 4 elements.
+public func destructure<Element>(_ elements: some Sequence<Element>) -> (
+    Element, Element, Element, Element
+)? {
     let array = Array(elements)
     guard array.count == 4 else {
         return nil
     }
     return (array[0], array[1], array[2], array[3])
 }
 
-public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element, Element, Element, Element)? {
+/// Destructures the given `elements` into a tuple of 5 elements if there are exactly 5 elements.
+public func destructure<Element>(_ elements: some Sequence<Element>) -> (
+    Element, Element, Element, Element, Element
+)? {
     let array = Array(elements)
     guard array.count == 5 else {
         return nil
     }
     return (array[0], array[1], array[2], array[3], array[4])
 }
 
-public func destructure<Element>(_ elements: some Sequence<Element>) -> (Element, Element, Element, Element, Element, Element)? {
+/// Destructures the given `elements` into a tuple of 6 elements if there are exactly 6 elements.
+public func destructure<Element>(_ elements: some Sequence<Element>) -> (
+    Element, Element, Element, Element, Element, Element
+)? {
     let array = Array(elements)
     guard array.count == 6 else {
         return nil
@@ -148,7 +161,7 @@ public func destructure(_ type: FunctionType) -> ((Type, Type, Type, Type, Type,
 public func destructure(_ type: Type) -> DestructuredType<()>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -164,7 +177,7 @@ public func destructure(_ type: Type) -> DestructuredType<()>? {
 public func destructureSingle(_ type: Type) -> DestructuredType<(Type)>? {
     if let type = type.asSimpleType {
         return destructureSingle(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructureSingle(type).map { destructured in
@@ -178,7 +191,7 @@ public func destructureSingle(_ type: Type) -> DestructuredType<(Type)>? {
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -192,7 +205,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type)>? {
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -206,7 +219,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type)>? {
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -220,7 +233,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Typ
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -234,7 +247,7 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Typ
 public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Type, Type, Type)>? {
     if let type = type.asSimpleType {
         return destructure(type).map { destructured in
-            .nominal(name: destructured.0, genericArguments: destructured.1)
+            .simple(name: destructured.0, genericArguments: destructured.1)
         }
     } else if let type = type.asFunctionType {
         return destructure(type).map { destructured in
@@ -245,8 +258,10 @@ public func destructure(_ type: Type) -> DestructuredType<(Type, Type, Type, Typ
     }
 }
 
-/// A destructured type (e.g. `Result<Success, Failure>` => `.nominal(name: "Result", genericArguments: ("Success", "Failure"))`).
+/// A destructured type (e.g. `Result<Success, Failure>` becomes `.simple(name: "Result", genericArguments: ("Success", "Failure"))`).
 public enum DestructuredType<TypeList> {
-    case nominal(name: String, genericArguments: TypeList)
+    /// A simple type (often referred to as a nominal type) such as `Int` or `Array<String>`.
+    case simple(name: String, genericArguments: TypeList)
+    /// A function type such as `(Int) -> Void`.
     case function(parameterTypes: TypeList, returnType: Type)
 }

Sources/MacroToolkit/Documentation.docc/Destructuring.md

@@ -0,0 +1,3 @@
+# Destructuring
+
+Destructuring is a game changer for developing robust macros without drowning yourself in verbose input validation code.