Inconsistency in documentation brought up by docc v6 (#80)

hummingbird-project · Sep 15, 2024 · f37842a · f37842a
1 parent fba2bb2
commit f37842a
Show file tree

Hide file tree

Showing 7 changed files with 26 additions and 19 deletions.
diff --git a/Sources/HummingbirdWSClient/Exports.swift b/Sources/HummingbirdWSClient/Exports.swift
@@ -12,4 +12,4 @@
 //
 //===----------------------------------------------------------------------===//
 
-@_exported import HummingbirdWSCore
+@_exported @_documentation(visibility: internal) import HummingbirdWSCore
diff --git a/Sources/HummingbirdWSClient/WebSocketClient.swift b/Sources/HummingbirdWSClient/WebSocketClient.swift
@@ -40,7 +40,7 @@ import NIOWebSocket
 /// }
 /// ```
 public struct WebSocketClient {
-    /// Basic context implementation of ``WebSocketContext``.
+    /// Basic context implementation of ``/HummingbirdWSCore/WebSocketContext``.
     /// Used by non-router web socket handle function
     public struct Context: WebSocketContext {
         public let logger: Logger

diff --git a/Sources/HummingbirdWSCore/WebSocketExtension.swift b/Sources/HummingbirdWSCore/WebSocketExtension.swift
@@ -157,7 +157,6 @@ public struct WebSocketExtensionHTTPParameters: Sendable, Equatable {
     /// Parse all `Sec-WebSocket-Extensions` header values
     /// - Parameters:
     ///   - headers: headers coming from other
-    ///   - type: client or server
     /// - Returns: Array of extensions
     public static func parseHeaders(_ headers: HTTPFields) -> [WebSocketExtensionHTTPParameters] {
         let extHeaders = headers[values: .secWebSocketExtensions]

diff --git a/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift b/Sources/HummingbirdWSCore/WebSocketInboundMessageStream.swift
@@ -43,7 +43,7 @@ extension WebSocketInboundStream {
     /// converts the inbound stream of WebSocket data frames into a sequence of WebSocket
     /// messages.
     ///
-    /// - Parameter maxMessageSize: The maximum size of message we are allowed to create
+    /// - Parameter maxSize: The maximum size of message we are allowed to read
     public func messages(maxSize: Int) -> WebSocketInboundMessageStream {
         .init(inboundStream: self, maxSize: maxSize)
     }

diff --git a/Sources/HummingbirdWebSocket/Exports.swift b/Sources/HummingbirdWebSocket/Exports.swift
@@ -12,4 +12,4 @@
 //
 //===----------------------------------------------------------------------===//
 
-@_exported import HummingbirdWSCore
+@_exported @_documentation(visibility: internal) import HummingbirdWSCore
diff --git a/Sources/HummingbirdWebSocket/WebSocketChannel.swift b/Sources/HummingbirdWebSocket/WebSocketChannel.swift
@@ -39,7 +39,7 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl
         public let channel: Channel
     }
 
-    /// Basic context implementation of ``WebSocketContext``.
+    /// Basic context implementation of ``/HummingbirdWSCore/WebSocketContext``.
     /// Used by non-router web socket handle function
     public struct Context: WebSocketContext {
         public let logger: Logger
@@ -51,11 +51,10 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl
 
     ///  Initialize HTTP1AndWebSocketChannel with synchronous `shouldUpgrade` function
     /// - Parameters:
-    ///   - additionalChannelHandlers: Additional channel handlers to add
     ///   - responder: HTTP responder
-    ///   - maxFrameSize: Max frame size WebSocket will allow
+    ///   - configuration: WebSocket configuration
+    ///   - additionalChannelHandlers: Additional channel handlers to add
     ///   - shouldUpgrade: Function returning whether upgrade should be allowed
-    /// - Returns: Upgrade result future
     public init(
         responder: @escaping HTTPChannelHandler.Responder,
         configuration: WebSocketServerConfiguration,
@@ -97,13 +96,23 @@ public struct HTTP1WebSocketUpgradeChannel: ServerChildChannel, HTTPChannelHandl
         self.responder = responder
     }
 
+    @available(*, deprecated, renamed: "init(responder:configuration:additionalChannelHandlers:shouldUpgrade:)")
+    @_documentation(visibility: internal)
+    public init(
+        responder: @escaping HTTPChannelHandler.Responder,
+        additionalChannelHandlers: @escaping @Sendable () -> [any RemovableChannelHandler] = { [] },
+        configuration: WebSocketServerConfiguration,
+        shouldUpgrade: @escaping @Sendable (HTTPRequest, Channel, Logger) async throws -> ShouldUpgradeResult<WebSocketDataHandler<Context>>
+    ) {
+        self.init(responder: responder, configuration: configuration, additionalChannelHandlers: additionalChannelHandlers, shouldUpgrade: shouldUpgrade)
+    }
+
     ///  Initialize HTTP1AndWebSocketChannel with async `shouldUpgrade` function
     /// - Parameters:
-    ///   - additionalChannelHandlers: Additional channel handlers to add
     ///   - responder: HTTP responder
-    ///   - maxFrameSize: Max frame size WebSocket will allow
+    ///   - additionalChannelHandlers: Additional channel handlers to add
+    ///   - configuration: WebSocket configuration
     ///   - shouldUpgrade: Function returning whether upgrade should be allowed
-    /// - Returns: Upgrade result future
     public init(
         responder: @escaping HTTPChannelHandler.Responder,
         configuration: WebSocketServerConfiguration,

diff --git a/Sources/HummingbirdWebSocket/WebSocketRouter.swift b/Sources/HummingbirdWebSocket/WebSocketRouter.swift
@@ -85,7 +85,7 @@ extension RouterMethods {
     /// - Parameters:
     ///   - path: Path to match
     ///   - shouldUpgrade: Should request be upgraded
-    ///   - handler: WebSocket channel handler
+    ///   - handler: WebSocket channel handler function
     @discardableResult public func ws(
         _ path: RouterPath = "",
         shouldUpgrade: @Sendable @escaping (Request, Context) async throws -> RouterShouldUpgrade = { _, _ in .upgrade([:]) },
@@ -115,7 +115,7 @@ public struct WebSocketUpgradeMiddleware<Context: WebSocketRequestContext>: Rout
     /// Initialize WebSocketUpgradeMiddleare
     /// - Parameters:
     ///   - shouldUpgrade: Return whether the WebSocket upgrade should occur
-    ///   - handle: WebSocket handler
+    ///   - handler: WebSocket handler function
     public init(
         shouldUpgrade: @Sendable @escaping (Request, Context) async throws -> RouterShouldUpgrade = { _, _ in .upgrade([:]) },
         onUpgrade handler: @escaping WebSocketDataHandler<WebSocketRouterContext<Context>>
@@ -140,11 +140,10 @@ public struct WebSocketUpgradeMiddleware<Context: WebSocketRequestContext>: Rout
 extension HTTP1WebSocketUpgradeChannel {
     ///  Initialize HTTP1WebSocketUpgradeChannel with async `shouldUpgrade` function
     /// - Parameters:
-    ///   - additionalChannelHandlers: Additional channel handlers to add
     ///   - responder: HTTP responder
-    ///   - maxFrameSize: Max frame size WebSocket will allow
-    ///   - webSocketRouter: WebSocket router
-    /// - Returns: Upgrade result future
+    ///   - webSocketResponder: WebSocket initial request responder
+    ///   - configuration: WebSocket configuration
+    ///   - additionalChannelHandlers: Additional channel handlers to add
     public init<WSResponder: HTTPResponder>(
         responder: @escaping HTTPChannelHandler.Responder,
         webSocketResponder: WSResponder,
@@ -207,7 +206,7 @@ extension HTTPServerBuilder {
     ///   - webSocketRouter: Router used for testing whether a WebSocket upgrade should occur
     ///   - configuration: WebSocket server configuration
     ///   - additionalChannelHandlers: Additional channel handlers to add to channel pipeline
-    /// - Returns:
+    /// - Returns: HTTP server builder that builds an HTTP1 with WebSocket upgrade server
     public static func http1WebSocketUpgrade<WSResponderBuilder: HTTPResponderBuilder>(
         webSocketRouter: WSResponderBuilder,
         configuration: WebSocketServerConfiguration = .init(),