docs: Document all types and members with SwiftDoc comments

Add SwiftDoc comments to every type and member across the app, editor
extension, and shared code, including private and internal declarations,
IBOutlets, IBActions, and KVO-observable properties.

Existing partial or free-form comments were validated and converted to
SwiftDoc, with parameter, return, and throws tags added where relevant.
In-body implementation comments are left unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: macmade

EditorExtension/SourceEditorCommand.swift

@@ -26,8 +26,26 @@ import Foundation
 import UniformTypeIdentifiers
 import XcodeKit
 
+/// The Xcode source editor command that formats the active buffer.
+///
+/// Invoked from Xcode's *Editor ▸ XcodeFormat* menu, it picks the formatter
+/// matching the buffer's type — SwiftFormat for Swift, uncrustify for the C
+/// family — using the user's selected configuration, then rewrites the buffer
+/// and restores the caret.
 public class SourceEditorCommand: NSObject, XCSourceEditorCommand
 {
+    /// Entry point Xcode calls to run the command on the current buffer.
+    ///
+    /// Resolves the selected configuration and the buffer's uniform type, makes
+    /// the needed configuration files available locally, and formats the buffer
+    /// with the matching tool. Does nothing (reporting success) when there is no
+    /// selected configuration or the buffer's type is unknown.
+    ///
+    /// - Parameters:
+    ///   - invocation:        The buffer and command context provided by Xcode.
+    ///   - completionHandler: Called once formatting finishes; receives an error
+    ///                        to surface in Xcode's banner, or `nil` on success
+    ///                        or a silent no-op.
     public func perform( with invocation: XCSourceEditorCommandInvocation, completionHandler: @escaping ( Error? ) -> Void )
     {
         guard let configuration = Preferences.shared.selectedConfiguration,
@@ -67,6 +85,22 @@ public class SourceEditorCommand: NSObject, XCSourceEditorCommand
         }
     }
 
+    /// Runs a formatter over the buffer's full contents and, if it produced
+    /// changed output, replaces the buffer and restores the caret.
+    ///
+    /// The buffer text is piped to the executable as UTF-8 standard input. The
+    /// result is classified by ``FormatterOutcome``; only a `.formatted`
+    /// outcome rewrites the buffer. When a single (empty) selection exists, its
+    /// caret is mapped onto the formatted text via
+    /// ``CursorPosition/restored(in:line:column:)``.
+    ///
+    /// - Parameters:
+    ///   - buffer:     The source buffer to read from and write back to.
+    ///   - executable: Name of the formatter executable to run.
+    ///   - arguments:  Command-line arguments for the formatter.
+    /// - Throws: ``FormatterError/executableNotFound(_:)`` if the tool could not
+    ///           be launched, or ``FormatterError/failed(executable:status:message:)``
+    ///           if it exited with a non-zero status.
     private func format( buffer: XCSourceTextBuffer, executable: String, arguments: [ String ] ) throws
     {
         guard let data = buffer.completeBuffer.data( using: .utf8 )

EditorExtension/SourceEditorExtension.swift

@@ -25,8 +25,15 @@
 import Foundation
 import XcodeKit
 
+/// The Xcode source editor extension principal object.
+///
+/// Xcode instantiates it when the extension is loaded; it warms the local
+/// cache by downloading each known configuration so a format command can run
+/// without waiting on the network.
 class SourceEditorExtension: NSObject, XCSourceEditorExtension
 {
+    /// Called by Xcode once the extension has launched; kicks off a download of
+    /// every stored configuration to populate the shared cache.
     func extensionDidFinishLaunching()
     {
         Preferences.shared.configurations.forEach

Shared/Configuration.swift

@@ -25,14 +25,31 @@
 import CryptoKit
 import Foundation
 
+/// A named formatting profile pairing a SwiftFormat configuration URL with an
+/// uncrustify configuration URL.
+///
+/// Configurations are persisted via ``Preferences`` and synced between the
+/// main app and the editor extension. Each remote configuration file is
+/// downloaded over HTTPS into the shared app-group container, keyed by a hash
+/// of its URL and stored alongside a content hash so a tampered or partial
+/// cache can be rejected at read time.
 @objc
 public class Configuration: NSObject, Codable
 {
+    /// User-visible name of the configuration.
     @objc public dynamic var name:         String
+
+    /// URL of the SwiftFormat configuration file, or `nil` if none.
     @objc public dynamic var swiftFormat:  URL?
+
+    /// URL of the uncrustify configuration file, or `nil` if none.
     @objc public dynamic var uncrustify:   URL?
+
+    /// Whether a download of this configuration's files is in progress.
+    /// KVO-observable so UI can show progress.
     @objc public dynamic var downloading = false
 
+    /// The built-in configurations seeded on first launch.
     public static var defaultConfigurations: [ Configuration ]
     {
         [
@@ -43,6 +60,13 @@ public class Configuration: NSObject, Codable
         ]
     }
 
+    /// Creates a configuration from a name and an optional URL for each
+    /// formatter.
+    ///
+    /// - Parameters:
+    ///   - name:        User-visible name.
+    ///   - swiftFormat: SwiftFormat configuration URL, or `nil`.
+    ///   - uncrustify:  Uncrustify configuration URL, or `nil`.
     public init( name: String, swiftFormat: URL?, uncrustify: URL? )
     {
         self.name        = name
@@ -52,11 +76,17 @@ public class Configuration: NSObject, Codable
         super.init()
     }
 
+    /// A textual description including the configuration's name, for debugging.
     public override var description: String
     {
         "\( super.description ): \( self.name )"
     }
 
+    /// Compares two configurations by value.
+    ///
+    /// - Parameter object: The object to compare against.
+    /// - Returns: `true` when `object` is a `Configuration` with the same name
+    ///            and formatter URLs.
     public override func isEqual( _ object: Any? ) -> Bool
     {
         guard let configuration = object as? Configuration
@@ -75,6 +105,8 @@ public class Configuration: NSObject, Codable
         return false
     }
 
+    /// A hash derived from the name and formatter URLs, consistent with
+    /// ``isEqual(_:)``.
     public override var hash: Int
     {
         var hasher = Hasher()
@@ -86,6 +118,11 @@ public class Configuration: NSObject, Codable
         return hasher.finalize()
     }
 
+    /// Downloads this configuration's formatter files into the shared cache.
+    ///
+    /// Coalesces concurrent calls via the ``downloading`` flag (checked and set
+    /// on the main queue), then fetches each non-`nil` URL on a background
+    /// queue, clearing the flag when finished.
     public func download()
     {
         DispatchQueue.main.async
@@ -117,6 +154,15 @@ public class Configuration: NSObject, Codable
         }
     }
 
+    /// Downloads a single configuration file and writes it to the shared cache.
+    ///
+    /// Rejects non-HTTPS URLs, names the cached file by the hash of its URL,
+    /// and writes a `<hash>.sha256` sidecar holding the content hash so the
+    /// cache can be integrity-checked on read. File writes are serialized
+    /// through an `NSFileCoordinator`. Any failure is silently ignored, leaving
+    /// the cache untouched.
+    ///
+    /// - Parameter url: HTTPS URL of the configuration file to fetch.
     private func download( url: URL )
     {
         guard url.scheme?.lowercased() == "https",
@@ -154,6 +200,10 @@ public class Configuration: NSObject, Codable
     /// Fetches a configuration over HTTPS with an explicit timeout, returning
     /// the body only for a 2xx response. Runs synchronously; intended to be
     /// called from a background queue.
+    ///
+    /// - Parameter url: URL of the configuration file to fetch.
+    /// - Returns: The response body for a 2xx response, or `nil` on a transport
+    ///            error or non-2xx status.
     private static func fetch( url: URL ) -> Data?
     {
         var request        = URLRequest( url: url, timeoutInterval: 30 )
@@ -189,6 +239,23 @@ public class Configuration: NSObject, Codable
         return result
     }
 
+    /// Provides local copies of the cached configuration files to a closure,
+    /// then lets the caller clean them up.
+    ///
+    /// Each available file is copied to a unique temporary location (its
+    /// integrity verified against the stored content hash). If a configured URL
+    /// has no valid cached copy, a fresh ``download()`` is triggered for next
+    /// time. When neither file is available the `error` closure is called and
+    /// `completion` is not. Otherwise `completion` receives the temporary URLs
+    /// plus a `finished` closure that deletes them; the caller must invoke
+    /// `finished` once done.
+    ///
+    /// - Parameters:
+    ///   - completion: Called with the temporary `swiftFormat` / `uncrustify`
+    ///                 URLs (either may be `nil`) and a `finished` cleanup
+    ///                 closure.
+    ///   - error:      Called instead of `completion` when no cached file is
+    ///                 available.
     public func withConfigurations( completion: ( ( swiftFormat: URL?, uncrustify: URL?, finished: () -> Void ) ) -> Void, error: () -> Void )
     {
         let swiftFormat = self.copy( url: self.swiftFormat )
@@ -225,6 +292,19 @@ public class Configuration: NSObject, Codable
         completion( ( swiftFormat: swiftFormat, uncrustify: uncrustify, finished: finished ) )
     }
 
+    /// Copies a cached configuration file to a unique temporary URL after
+    /// verifying its integrity.
+    ///
+    /// Locates the cached file by the hash of `url`, and — when a `<hash>.sha256`
+    /// sidecar exists — rejects the copy if the bytes no longer match, so a
+    /// tampered or partially written cache is never fed to the formatter. File
+    /// access is serialized through an `NSFileCoordinator`.
+    ///
+    /// - Parameter url: The original configuration URL whose cached copy is
+    ///                  wanted, or `nil`.
+    /// - Returns: A temporary URL holding a fresh copy of the cached file, or
+    ///            `nil` if `url` is `nil`, nothing is cached, or the integrity
+    ///            check or copy fails.
     private func copy( url: URL? ) -> URL?
     {
         guard let url       = url,

Shared/ConfigurationURLError.swift

@@ -34,6 +34,7 @@ public enum ConfigurationURLError: LocalizedError, Equatable
     /// The URL is well-formed but does not use the `https` scheme.
     case insecure
 
+    /// A localized, user-facing message describing why the URL was rejected.
     public var errorDescription: String?
     {
         switch self

Shared/CursorPosition.swift

@@ -28,9 +28,17 @@ import Foundation
 /// convention of `XCSourceTextPosition` (columns are UTF-16 code-unit offsets).
 public struct CursorPosition: Equatable
 {
+    /// Zero-based line index of the caret.
     public let line:   Int
+
+    /// Zero-based column of the caret, measured in UTF-16 code units.
     public let column: Int
 
+    /// Creates a cursor position from a line index and column.
+    ///
+    /// - Parameters:
+    ///   - line:   Zero-based line index.
+    ///   - column: Zero-based column, in UTF-16 code units.
     public init( line: Int, column: Int )
     {
         self.line   = line

Shared/Extensions/Data.swift

@@ -25,8 +25,11 @@
 import CryptoKit
 import Foundation
 
+/// SHA-256 hashing helper for raw bytes.
 public extension Data
 {
+    /// The SHA-256 digest of the bytes, formatted as an uppercase hexadecimal
+    /// string.
     var sha256: String
     {
         SHA256.hash( data: self ).compactMap

Shared/Extensions/FileManager.swift

@@ -24,8 +24,13 @@
 
 import Foundation
 
+/// Access to the app group's shared container, used to exchange cached
+/// configuration files between the app and the editor extension.
 public extension FileManager
 {
+    /// URL of the app group's shared container, used to exchange cached
+    /// configuration files between the main app and the editor extension, or
+    /// `nil` if the container is unavailable.
     static var sharedContainerURL: URL?
     {
         FileManager.default.containerURL( forSecurityApplicationGroupIdentifier: "326Y53CJMD.com.xs-labs.XcodeFormat.Shared" )

Shared/Extensions/String.swift

@@ -24,8 +24,11 @@
 
 import Foundation
 
+/// SHA-256 hashing helper for string contents.
 public extension String
 {
+    /// The SHA-256 digest of the string's UTF-8 bytes as an uppercase
+    /// hexadecimal string, or `nil` if the string cannot be UTF-8 encoded.
     var sha256: String?
     {
         self.data( using: .utf8 )?.sha256

Shared/Extensions/URL.swift

@@ -24,8 +24,12 @@
 
 import Foundation
 
+/// Hashing and validation helpers for configuration URLs.
 public extension URL
 {
+    /// The SHA-256 digest of the URL's absolute string as an uppercase
+    /// hexadecimal string, used to derive a stable cache file name for a
+    /// configuration URL.
     var sha256: String?
     {
         self.absoluteString.sha256

Shared/FormatterError.swift

@@ -35,6 +35,8 @@ public enum FormatterError: LocalizedError, Equatable
     /// its captured standard-error text.
     case failed( executable: String, status: Int32, message: String )
 
+    /// A localized, user-facing description of the failure, including the
+    /// formatter's trimmed standard-error text when one is available.
     public var errorDescription: String?
     {
         switch self