Document all type syntax wrappers and the associated TypeProtocol protocol

Author: stackotter

AddCompletionHandler.swift

@@ -1,11 +1,14 @@
 import SwiftSyntax
 
-/// Wraps a class restriction type (i.e. `any Protocol` or `some Protocol`).
+/// Wraps a constrained sugar type (i.e. `any Protocol` or `some Protocol`).
 public struct ConstrainedSugarType: TypeProtocol {
     public var _baseSyntax: ConstrainedSugarTypeSyntax
     public var _attributedSyntax: AttributedTypeSyntax?
 
-    public init(_ syntax: ConstrainedSugarTypeSyntax, attributedSyntax: AttributedTypeSyntax? = nil) {
+    public init(
+        _ syntax: ConstrainedSugarTypeSyntax,
+        attributedSyntax: AttributedTypeSyntax? = nil
+    ) {
         _baseSyntax = syntax
         _attributedSyntax = attributedSyntax
     }

Sources/MacroToolkit/ConstrainedSugarType.swift

@@ -13,10 +13,12 @@ public struct FunctionType: TypeProtocol {
         _attributedSyntax = attributedSyntax
     }
 
+    /// The return type that the function type describes.
     public var returnType: Type {
         Type(_baseSyntax.output.returnType)
     }
 
+    /// The types of the parameters the function type describes.
     public var parameters: [Type] {
         _baseSyntax.arguments.map(\.type).map(Type.init)
     }

Sources/MacroToolkit/FunctionType.swift

@@ -1,11 +1,14 @@
 import SwiftSyntax
 
-/// Wraps a member type (e.g. `Foundation.URL`).
+/// Wraps a member type (e.g. `Array<Int>.Element`).
 public struct MemberType: TypeProtocol {
     public var _baseSyntax: MemberTypeIdentifierSyntax
     public var _attributedSyntax: AttributedTypeSyntax?
 
-    public init(_ syntax: MemberTypeIdentifierSyntax, attributedSyntax: AttributedTypeSyntax? = nil) {
+    public init(
+        _ syntax: MemberTypeIdentifierSyntax,
+        attributedSyntax: AttributedTypeSyntax? = nil
+    ) {
         _baseSyntax = syntax
         _attributedSyntax = attributedSyntax
     }

Sources/MacroToolkit/MemberTypeIdentifierSyntax.swift renamed to Sources/MacroToolkit/MemberType.swift

@@ -5,15 +5,21 @@ public struct SimpleType: TypeProtocol {
     public var _baseSyntax: SimpleTypeIdentifierSyntax
     public var _attributedSyntax: AttributedTypeSyntax?
 
-    public init(_ syntax: SimpleTypeIdentifierSyntax, attributedSyntax: AttributedTypeSyntax? = nil) {
+    public init(
+        _ syntax: SimpleTypeIdentifierSyntax,
+        attributedSyntax: AttributedTypeSyntax? = nil
+    ) {
         _baseSyntax = syntax
         _attributedSyntax = attributedSyntax
     }
 
+    /// The base type's name (e.g. for `Array<Int>` it would be `"Array"`).
     public var name: String {
         _baseSyntax.name.description
     }
 
+    /// The type's generic arguments if any were supplied (e.g. for
+    /// `Dictionary<Int, String>` it would be `["Int", "String"]`).
     public var genericArguments: [Type]? {
         _baseSyntax.genericArgumentClause.map { clause in
             clause.arguments.map(\.argumentType).map(Type.init)

Sources/MacroToolkit/SimpleType.swift

@@ -1,26 +1,43 @@
 import SwiftSyntax
 import SwiftSyntaxBuilder
 
-// TODO: Always normalize typed and pretend sugar doesn't exist (e.g. Int? looks like Optional<Int> to devs)
+// TODO: Implement type normalisation and pretend sugar doesn't exist (e.g. Int? looks like Optional<Int> to devs)
 /// Wraps type syntax (e.g. `Result<Success, Failure>`).
 public enum Type: TypeProtocol, SyntaxExpressibleByStringInterpolation {
+    /// An array type (e.g. `[Int]`).
     case array(ArrayType)
+    /// A `class` token in a conformance list. Equivalent to `AnyObject`.
     case classRestriction(ClassRestrictionType)
+    /// A composition of two types (e.g. `Encodable & Decodable`). Used to
+    /// combine protocol requirements.
     case composition(CompositionType)
+    /// A sugared protocl type (e.g. `any T` or `some T`).
     case constrainedSugar(ConstrainedSugarType)
+    /// A dictionary type (e.g. `[Int: String]`).
     case dictionary(DictionaryType)
+    /// A function type (e.g. `() -> ()`).
     case function(FunctionType)
+    /// An implicitly unwrapped optional type (e.g. `Int!`).
     case implicitlyUnwrappedOptional(ImplicitlyUnwrappedOptionalType)
+    /// A member type (e.g. `Array<Int>.Element`).
     case member(MemberType)
+    /// A metatype (e.g. `Int.Type` or `Encodable.Protocol`).
     case metatype(MetatypeType)
+    /// A placeholder for invalid types that the resilient parser ignored.
     case missing(MissingType)
+    /// An optional type (e.g. `Int?`).
     case optional(OptionalType)
+    /// A pack expansion type (e.g. `repeat each V`).
     case packExpansion(PackExpansionType)
+    /// A pack reference type (e.g. `each V`).
     case packReference(PackReferenceType)
+    /// A simple type (e.g. `Int` or `Box<Int>`).
     case simple(SimpleType)
+    /// A suppressed type in a conformance position (e.g. `~Copyable`).
     case suppressed(SuppressedType)
+    //// A tuple type (e.g. `(Int, String)`).
     case tuple(TupleType)
-    
+
     public var _baseSyntax: TypeSyntax {
         let type: any TypeProtocol = switch self {
             case .array(let type): type
@@ -65,11 +82,11 @@ public enum Type: TypeProtocol, SyntaxExpressibleByStringInterpolation {
         return type._attributedSyntax
     }
 
+    /// Wrap a ``TypeSyntax`` (e.g. `Int?` or `MyStruct<[String]>!`).
     public init(_ syntax: TypeSyntax) {
         self.init(syntax, attributedSyntax: nil)
     }
 
-    /// Ignore the `attributedSyntax` attribute; it exists because of protocol conformance.
     public init(_ syntax: TypeSyntax, attributedSyntax: AttributedTypeSyntax? = nil) {
         // TODO: Move this weird initializer to an internal protocol if possible
         let syntax: TypeSyntaxProtocol = attributedSyntax ?? syntax
@@ -110,11 +127,15 @@ public enum Type: TypeProtocol, SyntaxExpressibleByStringInterpolation {
         }
     }
 
+    // TODO: add an optional version to all type syntax wrappers maybe?
+    /// Allows string interpolation syntax to be used to express type syntax.
     public init(stringInterpolation: SyntaxStringInterpolation) {
         self.init(TypeSyntax(stringInterpolation: stringInterpolation))
     }
 
+    /// A normalized description of the type (e.g. for `()` this would be `Void`).
     public var normalizedDescription: String {
+        // TODO: Implement proper type normalization
         // TODO: Normalize types nested within the type too (e.g. the parameter types of a function type)
         if let tupleSyntax = _syntax.as(TupleTypeSyntax.self) {
             if tupleSyntax.elements.count == 0 {
@@ -130,28 +151,33 @@ public enum Type: TypeProtocol, SyntaxExpressibleByStringInterpolation {
         }
     }
 
+    /// Gets whether the type is a void type (i.e. `Void`, `()`, `(Void)`, `((((()))))`, etc.).
     public var isVoid: Bool {
         normalizedDescription == "Void"
     }
 
     // TODO: Generate type conversions with macro?
+    /// Attempts to get the type as a simple type.
     public var asSimpleType: SimpleType? {
         switch self {
             case .simple(let type): type
             default: nil
         }
     }
 
+    /// Attempts to get the type as a function type.
     public var asFunctionType: FunctionType? {
         switch self {
             case .function(let type): type
             default: nil
         }
     }
+
+    // TODO: Implement rest of conversions
 }
 
-extension Optional<Type> {
-    /// If `nil`, the type is considered void, otherwise the underlying type is queried.
+extension Type? {
+    /// If `nil`, the type is considered void, otherwise the underlying type is queried (see ``Type/isVoid``).
     public var isVoid: Bool {
         if let self = self {
             return self.isVoid

Sources/MacroToolkit/Type.swift

@@ -1,35 +1,51 @@
 import SwiftSyntax
 
 public protocol TypeProtocol {
+    /// The underlying type syntax being wrapped.
     associatedtype WrappedSyntax: TypeSyntaxProtocol
+    /// The syntax associated with the type itself. For diagnostics ``_syntax``
+    /// may be better (as it includes the syntax for associated attributes).
     var _baseSyntax: WrappedSyntax { get }
+    /// The syntax associated with the attributes attached to the type (if any).
+    /// (e.g. the type `@escaping () -> ()` has the `@escaping` attribute).
     var _attributedSyntax: AttributedTypeSyntax? { get }
+    /// This initializer is an implementation detail and shouldn't need to be
+    /// used for most normal usecases.
     init(_ syntax: WrappedSyntax, attributedSyntax: AttributedTypeSyntax?)
 }
 
 extension TypeProtocol {
+    /// The syntax node referring to the entire type (including attributes if any).
+    /// Use for diagnostics.
     public var _syntax: any TypeSyntaxProtocol {
         _attributedSyntax ?? _baseSyntax
     }
 
+    /// A textual representation of the type without trivia (not normalized).
     public var description: String {
         _syntax.withoutTrivia().description
     }
 
+    /// Attempts to convert wrapped type syntax to this specific type of type syntax
+    /// (how confusing).
     public init?(_ type: Type) {
         guard let type = Self(type._syntax) else {
             return nil
         }
         self = type
     }
 
+    /// Initializes this type of type syntax from attributed syntax (the attributed
+    /// syntax's inner type syntax is passed to the regular `init` and the attributes
+    /// are stored in `_attributedTypeSyntax`).
     public init?(attributedSyntax: AttributedTypeSyntax) {
         guard let baseSyntax = attributedSyntax.baseType.as(WrappedSyntax.self) else {
             return nil
         }
         self.init(baseSyntax, attributedSyntax: attributedSyntax)
     }
 
+    /// Attempts to initialize this type of type syntax from arbitrary type syntax.
     public init?(_ syntax: any TypeSyntaxProtocol) {
         if let syntax = syntax.as(WrappedSyntax.self) {
             self.init(syntax, attributedSyntax: nil)