Add Dooc

Author: Andrea Scuderi

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [BreezeLambdaWebHook]

Makefile

@@ -26,4 +26,8 @@ test:
 coverage:
 	llvm-cov export $(TEST_PACKAGE) \
 		--instr-profile=$(SWIFT_BIN_PATH)/codecov/default.profdata \
-		--format=lcov > $(GITHUB_WORKSPACE)/lcov.info
+		--format=lcov > $(GITHUB_WORKSPACE)/lcov.info
+
+preview_docc_lambda_api:
+	swift package --disable-sandbox preview-documentation --target BreezeLambdaWebHook
+

Package.swift

@@ -22,7 +22,8 @@ let package = Package(
         .package(url: "https://github.com/andrea-scuderi/swift-aws-lambda-runtime.git", branch: "main"),
         .package(url: "https://github.com/swift-server/swift-aws-lambda-events.git", from: "0.5.0"),
         .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.22.0"),
-        .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", from: "2.6.3")
+        .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", from: "2.6.3"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         .target(

Sources/BreezeLambdaWebHook/APIGatewayV2Response+Extensions.swift

@@ -16,14 +16,16 @@ import struct AWSLambdaEvents.APIGatewayV2Response
 import HTTPTypes
 import class Foundation.JSONEncoder
 
+/// Extensions for `APIGatewayV2Response` to simplify response creation
 public extension APIGatewayV2Response {
     private static let encoder = JSONEncoder()
 
+    /// Body of an error response
     struct BodyError: Codable {
         public let error: String
     }
 
-    /// init
+    /// Initializer with body error and status code
     /// - Parameters:
     ///   - error: Error
     ///   - statusCode: HTTP Status Code
@@ -32,11 +34,16 @@ public extension APIGatewayV2Response {
         self.init(with: bodyError, statusCode: statusCode)
     }
 
-    /// init
+    /// Initializer with decodable object, status code, and headers
     /// - Parameters:
     ///   - object: Encodable Object
     ///   - statusCode: HTTP Status Code
     ///   - headers: HTTP Headers
+    ///  - Returns: APIGatewayV2Response
+    ///
+    ///  This initializer encodes the object to JSON and sets it as the body of the response.
+    ///  If encoding fails, it defaults to an empty JSON object.
+    ///  - Note: The `Content-Type` header is set to `application/json` by default.
     init<Output: Encodable>(
         with object: Output,
         statusCode: HTTPResponse.Status,

Sources/BreezeLambdaWebHook/BreezeHTTPClientConfig.swift

@@ -15,10 +15,13 @@
 import Logging
 import NIOCore
 
+/// Error types for BreezeClientService
 public enum BreezeClientServiceError: Error {
-    case invalidHttpClient
+    /// The handler is invalid or not set
+    case invalidHandler
 }
 
+/// Configuration for the Breeze HTTP Client
 public struct BreezeHTTPClientConfig: Sendable {
     public init(timeout: TimeAmount, logger: Logger) {
         self.timeout = timeout

Sources/BreezeLambdaWebHook/BreezeLambdaWebHook.swift

@@ -18,16 +18,29 @@ import ServiceLifecycle
 import Logging
 import NIOCore
 
+/// The Service that handles Breeze Lambda WebHook functionality.
 public struct BreezeLambdaWebHook<LambdaHandler: BreezeLambdaWebHookHandler>: Service {
 
+    /// The name of the service, used for logging and identification.
     public let name: String
+    /// Configuration for the Breeze HTTP Client.
     public let config: BreezeHTTPClientConfig
 
+    /// Initializes a new instance of with the given name and configuration.
+    /// - Parameters:
+    ///  - name: The name of the service.
+    ///  - config: Configuration for the Breeze HTTP Client.
     public init(name: String, config: BreezeHTTPClientConfig) {
         self.name = name
         self.config = config
     }
 
+    /// Runs the Breeze Lambda WebHook service.
+    /// - Throws: An error if the service fails to start or run.
+    ///
+    /// This method initializes the Breeze Lambda WebHook service and starts it,
+    /// handling any errors that may occur during the process.
+    /// It gracefully shuts down the service on termination signals.
     public func run() async throws {
         do {
             let lambdaService = BreezeLambdaWebHookService<LambdaHandler>(

Sources/BreezeLambdaWebHook/BreezeLambdaWebHookError.swift

@@ -14,6 +14,8 @@
 
 import Foundation
 
+/// Error types for BreezeLambdaWebHook
 public enum BreezeLambdaWebHookError: Error {
+    /// The request is invalid or malformed
     case invalidRequest
 }

Sources/BreezeLambdaWebHook/BreezeLambdaWebHookHandler.swift

@@ -23,10 +23,12 @@ public protocol BreezeLambdaWebHookHandler: LambdaHandler {
     func handle(_ event: APIGatewayV2Request, context: LambdaContext) async throws -> APIGatewayV2Response
 }
 
+/// A default implementation of the BreezeLambdaWebHookHandler protocol
 public extension BreezeLambdaWebHookHandler {
     var handler: String? {
         Lambda.env("_HANDLER")
     }
+    
     var httpClient: AsyncHTTPClient.HTTPClient {
         handlerContext.httpClient
     }

Sources/BreezeLambdaWebHook/BreezeLambdaWebHookService.swift

@@ -27,13 +27,19 @@ public struct HandlerContext: Sendable {
     }
 }
 
+/// A service that runs a Breeze Lambda WebHook handler
+///
+/// This service is responsible for providing the necessary context and configuration to the handler,
+/// including the HTTP client and any other required resources.
+///
+/// - Note: This service is designed to be used with the Breeze Lambda WebHook framework, which allows for handling webhooks in a serverless environment.
 public actor BreezeLambdaWebHookService<Handler: BreezeLambdaWebHookHandler>: Service {
 
     let config: BreezeHTTPClientConfig
     var handlerContext: HandlerContext?
     let httpClient: HTTPClient
-    private var isStarted = false
 
+    /// Initialilizer with a configuration for the Breeze HTTP Client.
     public init(config: BreezeHTTPClientConfig) {
         self.config = config
         let timeout = HTTPClient.Configuration.Timeout(
@@ -47,8 +53,8 @@ public actor BreezeLambdaWebHookService<Handler: BreezeLambdaWebHookHandler>: Se
         )
     }
 
+    /// Runs the Breeze Lambda WebHook service.
     public func run() async throws {
-        isStarted = true
         let handlerContext = HandlerContext(httpClient: httpClient)
         self.handlerContext = handlerContext
         let runtime = LambdaRuntime(body: handler)
@@ -61,9 +67,10 @@ public actor BreezeLambdaWebHookService<Handler: BreezeLambdaWebHookHandler>: Se
         }
     }
 
+    /// Handler function that processes incoming events.
     func handler(event: APIGatewayV2Request, context: LambdaContext) async throws -> APIGatewayV2Response {
         guard let handlerContext = handlerContext else {
-            throw BreezeClientServiceError.invalidHttpClient
+            throw BreezeClientServiceError.invalidHandler
         }
         return try await Handler(handlerContext: handlerContext).handle(event, context: context)
     }

Sources/BreezeLambdaWebHook/Docs.docc/theme-settings.json

@@ -0,0 +1,12 @@
+{
+    "theme": {
+        "color": {
+            "header": "#DE5E44",
+            "documentation-intro-title": "#FFFFFF",
+            "documentation-intro-fill":  "linear-gradient(30deg, #DE5E44, #A2331D)",
+            "documentation-intro-accent": "#FFFFFF",
+            "documentation-intro-eyebrow": "#FFFFFF",
+            "link": "var(--color-header)"
+        }
+    }
+}