docs: Adds type/func documentation

Also removes unhelpful comments

Author: NeedleInAJayStack

Package.swift

@@ -25,39 +25,30 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.3.0"),
     ],
     targets: [
-        // Build plugin that discovers .graphql files and invokes the generator
         .plugin(
             name: "GraphQLGeneratorPlugin",
             capability: .buildTool(),
             dependencies: ["GraphQLGenerator"]
         ),
-
-        // CLI executable that performs code generation
         .executableTarget(
             name: "GraphQLGenerator",
             dependencies: [
                 "GraphQLGeneratorCore",
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
             ]
         ),
-
-        // Core library with parsing and generation logic
         .target(
             name: "GraphQLGeneratorCore",
             dependencies: [
                 .product(name: "GraphQL", package: "GraphQL"),
             ]
         ),
-
-        // Runtime library for generated code
         .target(
             name: "GraphQLGeneratorRuntime",
             dependencies: [
                 .product(name: "GraphQL", package: "GraphQL"),
             ]
         ),
-
-        // Tests
         .testTarget(
             name: "GraphQLGeneratorCoreTests",
             dependencies: [

Sources/GraphQLGenerator/GraphQLGeneratorCommand.swift

@@ -26,39 +26,32 @@ struct GraphQLGeneratorCommand: ParsableCommand {
             print("Output directory: \(outputDirectory)")
         }
 
-        // Validate input files exist
         for filePath in schemaFiles {
             let fileURL = URL(fileURLWithPath: filePath)
             guard FileManager.default.fileExists(atPath: fileURL.path) else {
                 throw ValidationError("Schema file not found: \(filePath)")
             }
         }
 
-        // Create output directory if it doesn't exist
         let outputURL = URL(fileURLWithPath: outputDirectory)
         try FileManager.default.createDirectory(at: outputURL, withIntermediateDirectories: true)
 
         if verbose {
             print("Parsing schema files...")
         }
-
-        /// Read GraphQL schema files and combine them into a single schema
         var combinedSource = ""
         for filePath in schemaFiles {
             let url = URL(fileURLWithPath: filePath)
             let content = try String(contentsOf: url, encoding: .utf8)
             combinedSource += content + "\n"
         }
 
-        // Generate code
         let generator = CodeGenerator()
         let files = try generator.generate(source: combinedSource)
 
-        // Write generated files
         for (filename, content) in files {
             let fileURL = outputURL.appendingPathComponent(filename)
             try content.write(to: fileURL, atomically: true, encoding: .utf8)
-
             if verbose {
                 print("Generated: \(fileURL.path)")
             }

Sources/GraphQLGeneratorCore/Generator/CodeGenerator.swift

@@ -5,7 +5,7 @@ import GraphQL
 package struct CodeGenerator {
     package init() {}
 
-    /// Generate all Swift files from the schema
+    /// Generate all Swift files from the schema source string.
     /// Returns a dictionary of filename -> file content
     package func generate(source: String) throws -> [String: String] {
         let schema = try GraphQL.buildSchema(source: source)

Sources/GraphQLGeneratorRuntime/GraphQLScalar.swift

@@ -1,14 +1,20 @@
 import GraphQL
 import OrderedCollections
 
+/// A type that can act as a GraphQL scalar value
 public protocol GraphQLScalar: Sendable, Codable {
+    /// Given an instance of this type, it defines how to convert the instance into a GraphQL JSON Map
     static func serialize(this: Self) throws -> Map
+
+    /// Given any GraphQL JSON Map value, validate and conform it to a Map that represents this scalar
     static func parseValue(map: Map) throws -> Map
+
+    /// Given a literal value, validate it and return the corresponding GraphQL JSON Map
     static func parseLiteral(value: any Value) throws -> Map
 }
 
-// Graphiti provides default serializations that the underlying type's Codability requirements, but they are very
-// inefficient. They typically pass through a full serialize/deserialize step on each call.
+// Graphiti provides default serializations that use the underlying type's Codability requirements, but they are
+// somewhat inefficient. They typically pass through a full serialize/deserialize step on each call.
 // Because of this, we have chosen not to vend defaults to force the user to implement more performant versions.
 
 public extension GraphQLScalar {

Sources/GraphQLGeneratorRuntime/ResolverHelpers.swift

@@ -1,5 +1,6 @@
 import GraphQL
 
+/// Cast an `any Sendable` to the input type, or throw a GraphQL error.
 public func cast<T: Sendable>(_ anySendable: any Sendable, to _: T.Type) throws -> T {
     guard let result = anySendable as? T else {
         throw GraphQLError(