Added missing documentation throughout the package

Author: dimitribouniol

Package.swift

@@ -16,11 +16,16 @@ let package = Package(
         .library(name: "WebPushTesting", targets: ["WebPush", "WebPushTesting"]),
     ],
     dependencies: [
+        /// Core dependency that allows us to sign Authorization tokens and encrypt push messages per subscriber before delivery.
         .package(url: "https://github.com/apple/swift-crypto.git", "3.10.0"..<"5.0.0"),
+        /// Logging integration allowing runtime API missuse warnings and push status tracing.
         .package(url: "https://github.com/apple/swift-log.git", from: "1.6.2"),
-        .package(url: "https://github.com/apple/swift-nio.git", from: "2.77.0"),
-        .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.24.0"),
+        /// Service lifecycle integration for clean shutdowns in a server environment.
         .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", from: "2.6.2"),
+        /// Internal dependency allowing push message delivery over HTTP/2.
+        .package(url: "https://github.com/swift-server/async-http-client.git", from: "1.24.0"),
+        /// Internal dependency for event loop coordination and shared HTTP types.
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.77.0"),
     ],
     targets: [
         .target(

Sources/WebPush/Errors/BadSubscriberError.swift

@@ -12,6 +12,7 @@ import Foundation
 ///
 /// - Warning: Do not continue to send notifications to invalid subscriptions or you'll risk being rate limited by push services.
 public struct BadSubscriberError: LocalizedError, Hashable, Sendable {
+    /// Create a new bad subscriber error.
     public init() {}
 
     public var errorDescription: String? {

Sources/WebPush/Errors/Base64URLDecodingError.swift

@@ -10,6 +10,7 @@ import Foundation
 
 /// An error encountered while decoding Base64 data.
 public struct Base64URLDecodingError: LocalizedError, Hashable, Sendable {
+    /// Create a new base 64 decoding error.
     public init() {}
 
     public var errorDescription: String? {

Sources/WebPush/Errors/HTTPError.swift

@@ -15,9 +15,13 @@ import Foundation
 /// - SeeAlso: [RFC 8292 Voluntary Application Server Identification (VAPID) for Web Push](https://datatracker.ietf.org/doc/html/rfc8292)
 /// - SeeAlso: [Sending web push notifications in web apps and browsers — Review responses for push notification errors](https://developer.apple.com/documentation/usernotifications/sending-web-push-notifications-in-web-apps-and-browsers#Review-responses-for-push-notification-errors)
 public struct HTTPError: LocalizedError, Sendable {
+    /// The HTTP response that was returned from the push service..
     public let response: HTTPClientResponse
+    
+    /// A cached description from the response that won't change over the lifetime of the error.
     let capturedResponseDescription: String
 
+    /// Create a new http error.
     public init(response: HTTPClientResponse) {
         self.response = response
         self.capturedResponseDescription = "\(response)"

Sources/WebPush/Errors/MessageTooLargeError.swift

@@ -12,6 +12,7 @@ import Foundation
 ///
 /// - SeeAlso: ``WebPushManager/maximumMessageSize``
 public struct MessageTooLargeError: LocalizedError, Hashable, Sendable {
+    /// Create a new message too large error.
     public init() {}
 
     public var errorDescription: String? {

Sources/WebPush/Errors/UserAgentKeyMaterialError.swift

@@ -10,13 +10,19 @@ import Foundation
 
 /// An error encountered during ``VAPID/Configuration`` initialization or decoding.
 public struct UserAgentKeyMaterialError: LocalizedError, Sendable {
+    /// The kind of error that occured.
     enum Kind {
+        /// The public key was invalid.
         case invalidPublicKey
+        /// The authentication secret was invalid.
         case invalidAuthenticationSecret
     }
 
+    /// The kind of error that occured.
     var kind: Kind
-    var underlyingError: any Error
+    
+    /// The underlying error that caused this one.
+    public var underlyingError: any Error
 
     /// The public key was invalid.
     public static func invalidPublicKey(underlyingError: Error) -> Self {

Sources/WebPush/Errors/VAPIDConfigurationError.swift

@@ -11,11 +11,15 @@ import Foundation
 extension VAPID {
     /// An error encountered during ``VAPID/Configuration`` initialization or decoding.
     public struct ConfigurationError: LocalizedError, Hashable, Sendable {
+        /// The kind of error that occured.
         enum Kind {
+            /// VAPID keys not found during initialization.
             case keysNotProvided
+            /// A VAPID key for the subscriber was not found.
             case matchingKeyNotFound
         }
 
+        /// The kind of error that occured.
         var kind: Kind
 
         /// VAPID keys not found during initialization.

Sources/WebPush/Helpers/DataProtocol+Base64URLCoding.swift

@@ -9,6 +9,7 @@
 import Foundation
 
 extension DataProtocol {
+    /// The receiver as a Base64 URL encoded string.
     @_disfavoredOverload
     @usableFromInline
     func base64URLEncodedString() -> String {
@@ -21,6 +22,7 @@ extension DataProtocol {
 }
 
 extension ContiguousBytes {
+    /// The receiver as a Base64 URL encoded string.
     @usableFromInline
     func base64URLEncodedString() -> String {
         withUnsafeBytes { bytes in
@@ -30,6 +32,7 @@ extension ContiguousBytes {
 }
 
 extension DataProtocol where Self: RangeReplaceableCollection {
+    /// Initialize data using a Base64 URL encoded string.
     @usableFromInline
     init?(base64URLEncoded string: some StringProtocol) {
         var base64String = string.replacingOccurrences(of: "-", with: "+").replacingOccurrences(of: "_", with: "/")

Sources/WebPush/Helpers/HTTPClientProtocol.swift

@@ -10,13 +10,16 @@ import AsyncHTTPClient
 import Logging
 import NIOCore
 
+/// A protocol abstracting HTTP request execution.
 package protocol HTTPClientProtocol: Sendable {
+    /// Execute the request.
     func execute(
         _ request: HTTPClientRequest,
         deadline: NIODeadline,
         logger: Logger?
     ) async throws -> HTTPClientResponse
 
+    /// Shuts down the client.
     func syncShutdown() throws
 }
 

Sources/WebPush/Helpers/PrintLogHandler.swift

@@ -9,6 +9,7 @@
 import Foundation
 import Logging
 
+/// A simple log handler that uses formatted print statements.
 package struct PrintLogHandler: LogHandler {
     private let label: String
 

Sources/WebPush/VAPID/VAPID.swift

@@ -8,6 +8,7 @@
 
 import Foundation
 
+/// The fully qualified name for VAPID.
 public typealias VoluntaryApplicationServerIdentification = VAPID
 
 /// A set of types for Voluntary Application Server Identification, also known as VAPID.

Sources/WebPush/VAPID/VAPIDConfiguration.swift

@@ -157,6 +157,7 @@ extension VoluntaryApplicationServerIdentification {
 }
 
 extension VAPID.Configuration: Codable {
+    /// The coding keys used to encode a VAPID configuration.
     public enum CodingKeys: CodingKey {
         case primaryKey
         case keys
@@ -220,6 +221,7 @@ extension VAPID.Configuration {
         /// An email-based contact method.
         case email(String)
 
+        /// The string that representa the contact information as a fully-qualified URL.
         var urlString: String {
             switch self {
             case .url(let url):     url.absoluteURL.absoluteString

Sources/WebPush/VAPID/VAPIDKey.swift

@@ -68,8 +68,10 @@ extension VAPID.Key: Identifiable {
     ///
     /// - SeeAlso: [Push API Working Draft §7.2. `PushSubscriptionOptions` Interface](https://www.w3.org/TR/push-api/#pushsubscriptionoptions-interface)
     public struct ID: Hashable, Comparable, Codable, Sendable, CustomStringConvertible {
+        /// The raw string that represents the ID.
         private var rawValue: String
 
+        /// Initialize an ID with a raw string.
         init(_ rawValue: String) {
             self.rawValue = rawValue
         }

Sources/WebPush/VAPID/VAPIDToken.swift

@@ -16,6 +16,7 @@ extension VAPID {
     /// - SeeAlso: [RFC 7515 JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515)
     ///- SeeAlso: [RFC 7519 JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
     struct Token: Hashable, Codable, Sendable {
+        /// The coding keys used to encode the token.
         enum CodingKeys: String, CodingKey {
             case audience = "aud"
             case subject = "sub"
@@ -118,6 +119,7 @@ extension VAPID {
 }
 
 protocol VAPIDKeyProtocol: Identifiable, Sendable {
+    /// The signature type used by this key.
     associatedtype Signature: ContiguousBytes
 
     /// Returns a JWS signature for the message.

Sources/WebPush/WebPushManager.swift

@@ -134,6 +134,7 @@ public actor WebPushManager: Sendable {
         self.executor = executor
     }
 
+    /// Shutdown the client if it hasn't already been stopped.
     deinit {
         if !didShutdown, case let .httpClient(httpClient, _) = executor {
             try? httpClient.syncShutdown()