Add comprehensive documentation comments to DocumentationHarness public API

Added DocC-style documentation comments to all public and package access
level items in the DocumentationHarness module, including:

- Package structs: CodeBlock, ValidationResult, DocumentationTestHarness
- Package enums: TestType, ValidationError, ProcessError, FileSearchError, CodeBlockExtractorError
- Package protocols: SyntaxValidator, FileSearcher
- Package typealiases: CodeBlockExtractor
- All public properties and methods with parameter documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: leogdion

Sources/DocumentationHarness/CodeBlock.swift

@@ -29,8 +29,12 @@
 
 import Foundation
 
+/// Represents a code block extracted from documentation
 package struct CodeBlock {
+  /// The raw Swift code content
   internal let code: String
+  /// Line number where this code block starts in the source file
   internal let lineNumber: Int
+  /// The type of code block (example, shell command, etc.)
   internal let blockType: CodeBlockType
 }

Sources/DocumentationHarness/CodeBlockExtractor.swift

@@ -27,5 +27,9 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
+/// Function type for extracting code blocks from markdown content
+/// - Parameter content: The markdown content to parse
+/// - Returns: Array of extracted code blocks
+/// - Throws: CodeBlockExtractorError if extraction fails
 package typealias CodeBlockExtractor = @Sendable (String) throws(CodeBlockExtractorError) ->
   [CodeBlock]

Sources/DocumentationHarness/CodeBlockExtractorError.swift

@@ -27,7 +27,8 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
-/// Errors that can occur during code block extraction
+/// Errors that can occur during code block extraction from markdown
 package enum CodeBlockExtractorError: Error {
+  /// The extractor instance has already been used and cannot be reused
   case alreadyUsed
 }

Sources/DocumentationHarness/DocumentationTestHarness.swift

@@ -32,7 +32,7 @@ import SwiftParser
 import SwiftSyntax
 import Testing
 
-/// Harness for extracting and testing documentation code examples
+/// Test harness for extracting and validating Swift code examples from documentation
 package struct DocumentationTestHarness {
   /// Default file extensions for documentation files
   internal static let defaultPathExtensions = ["md"]
@@ -41,6 +41,11 @@ package struct DocumentationTestHarness {
   private let fileSearcher: any FileSearcher
   private let codeBlocksFrom: CodeBlockExtractor
 
+  /// Creates a new documentation test harness
+  /// - Parameters:
+  ///   - codeValidator: Validator for Swift code syntax (defaults to CodeSyntaxValidator)
+  ///   - fileSearcher: File system searcher (defaults to FileManager.default)
+  ///   - codeBlocksFrom: Function to extract code blocks from content
   package init(
     codeValidator: any SyntaxValidator = CodeSyntaxValidator(),
     fileSearcher: any FileSearcher = FileManager.default,
@@ -51,7 +56,13 @@ package struct DocumentationTestHarness {
     self.codeBlocksFrom = codeBlocksFrom
   }
 
-  /// Validates all code examples in all documentation files
+  /// Validates all Swift code examples found in documentation files
+  /// - Parameters:
+  ///   - relativePaths: Array of relative paths to search for documentation
+  ///   - projectRoot: Root URL of the project
+  ///   - pathExtensions: File extensions to search for (defaults to ["md"])
+  /// - Returns: Array of validation results for all code blocks found
+  /// - Throws: FileSearchError if file operations fail
   package func validate(
     relativePaths: [String], atProjectRoot projectRoot: URL,
     withPathExtensions pathExtensions: [String] = Self.defaultPathExtensions
@@ -73,7 +84,10 @@ package struct DocumentationTestHarness {
     return allResults
   }
 
-  /// Validates code examples in a specific file
+  /// Validates all Swift code examples in a specific documentation file
+  /// - Parameter fileURL: URL of the file to validate
+  /// - Returns: Array of validation results for code blocks in the file
+  /// - Throws: Error if file cannot be read or parsed
   package func validateExamplesInFile(_ fileURL: URL) throws -> [ValidationResult] {
     // let fullPath = try resolveFilePath(filePath)
     let content = try String(contentsOf: fileURL)

Sources/DocumentationHarness/FileSearchError.swift

@@ -29,11 +29,16 @@
 
 import Foundation
 
+/// Errors that can occur during file searching operations
 package enum FileSearchError: Error, LocalizedError {
+  /// Cannot access the specified path
   case cannotAccessPath(String, underlying: any Error)
+  /// Cannot read the contents of a directory
   case cannotReadDirectory(String, underlying: any Error)
+  /// An unknown error occurred
   case unknownError(any Error)
 
+  /// Human-readable description of the file search error
   package var errorDescription: String? {
     switch self {
     case .cannotAccessPath(let path, let underlying):

Sources/DocumentationHarness/FileSearcher.swift

@@ -29,7 +29,14 @@
 
 package import Foundation
 
+/// Protocol for searching files in directories
 package protocol FileSearcher {
+  /// Searches a directory for files with specific extensions
+  /// - Parameters:
+  ///   - path: The directory URL to search
+  ///   - pathExtensions: Array of file extensions to search for (without dots)
+  /// - Returns: Array of URLs for matching files
+  /// - Throws: FileSearchError if search fails
   func searchDirectory(at path: URL, forExtensions pathExtensions: [String]) throws(FileSearchError)
     -> [URL]
 }

Sources/DocumentationHarness/SyntaxValidator.swift

@@ -27,7 +27,11 @@
 //  OTHER DEALINGS IN THE SOFTWARE.
 //
 
+/// Protocol for validating Swift code syntax
 package protocol SyntaxValidator {
+  /// Validates the syntax of Swift code
+  /// - Parameter code: The Swift code to validate
+  /// - Throws: ValidationError if validation fails
   func validateCode(_ code: String) throws(ValidationError)
 }
 extension SyntaxValidator {

Sources/DocumentationHarness/TestType.swift

@@ -29,8 +29,12 @@
 
 import Foundation
 
+/// Represents the type of test performed on a code block
 package enum TestType {
+  /// Code was parsed for syntax validation only
   case parsing
+  /// Code was executed (compiled and run)
   case execution
+  /// Code validation was skipped
   case skipped
 }

Sources/DocumentationHarness/ValidationError.swift

@@ -29,15 +29,15 @@
 
 import Foundation
 
-/// Process execution errors
+/// Errors that can occur during process execution
 package enum ProcessError: Error, Sendable {
   /// Package.swift validation failed
   case packageValidationFailed
   /// Package validation setup failed
   case setupError(any Error)
 }
 
-/// Error type for Swift syntax validation failures
+/// Errors that can occur during Swift code validation
 package enum ValidationError: Error, Sendable {
   /// Syntax parsing detected errors in the code
   case syntaxError
@@ -51,7 +51,7 @@ package enum ValidationError: Error, Sendable {
   /// Unexpected error during validation
   case unexpectedError(any Error)
 
-  /// Reasons why code should be skipped
+  /// Reasons why code validation should be skipped
   package enum SkipReason: Equatable, Sendable {
     /// Package.swift or dependency configuration
     case packageFile
@@ -65,7 +65,7 @@ package enum ValidationError: Error, Sendable {
     case emptyOrTooShort
   }
 
-  /// Returns a human-readable description of the error
+  /// Human-readable description of the validation error
   package var localizedDescription: String {
     switch self {
     case .unexpectedError(let error):

Sources/DocumentationHarness/ValidationResult.swift

@@ -29,25 +29,31 @@
 
 package import Foundation
 
+/// Result of validating a code block from documentation
 package struct ValidationResult {
   internal let parameters: any ValidationParameters
+  /// The type of test that was performed
   package let testType: TestType
+  /// Any error that occurred during validation (nil if successful)
   package let error: ValidationError?
 
-  /// Returns true if validation was successful (no error)
+  /// Whether the validation was successful (no error occurred)
   package var isSuccess: Bool {
     error == nil
   }
 
+  /// Whether the validation was skipped
   package var isSkipped: Bool {
     error?.isSkipped ?? false
   }
 
   // MARK: - Convenience Properties
+  /// The URL of the file containing the validated code
   package var fileURL: URL {
     parameters.fileURL
   }
 
+  /// The line number where the code block starts
   package var lineNumber: Int {
     parameters.lineNumber
   }