Changes required by docc (#549)

Author: adam-fowler

Sources/Hummingbird/Codable/CodableProtocols.swift

@@ -21,6 +21,7 @@ public protocol ResponseEncoder {
     /// - Parameters:
     ///   - value: value to encode
     ///   - request: request that generated this value
+    ///   - context: Request context
     func encode(_ value: some Encodable, from request: Request, context: some RequestContext) throws -> Response
 }
 
@@ -30,5 +31,6 @@ public protocol RequestDecoder {
     /// - Parameters:
     ///   - type: type to decode to
     ///   - request: request
+    ///   - context: Request context
     func decode<T: Decodable>(_ type: T.Type, from request: Request, context: some RequestContext) async throws -> T
 }

Sources/Hummingbird/Codable/JSON/JSONCoding.swift

@@ -22,6 +22,7 @@ extension JSONEncoder: ResponseEncoder {
     /// - Parameters:
     ///   - value: Value to encode
     ///   - request: Request used to generate response
+    ///   - context: Request context
     public func encode(_ value: some Encodable, from request: Request, context: some RequestContext) throws -> Response {
         let data = try self.encode(value)
         let buffer = ByteBuffer(data: data)
@@ -41,6 +42,7 @@ extension JSONDecoder: RequestDecoder {
     /// - Parameters:
     ///   - type: Type to decode
     ///   - request: Request to decode from
+    ///   - context: Request context
     public func decode<T: Decodable>(_ type: T.Type, from request: Request, context: some RequestContext) async throws -> T {
         let buffer = try await request.body.collect(upTo: context.maxUploadSize)
         return try self.decode(T.self, from: buffer)

Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedForm+Request.swift

@@ -17,6 +17,7 @@ extension URLEncodedFormEncoder: ResponseEncoder {
     /// - Parameters:
     ///   - value: Value to encode
     ///   - request: Request used to generate response
+    ///   - context: Request context
     public func encode(_ value: some Encodable, from request: Request, context: some RequestContext) throws -> Response {
         let string = try self.encode(value)
         let buffer = ByteBuffer(string: string)
@@ -36,6 +37,7 @@ extension URLEncodedFormDecoder: RequestDecoder {
     /// - Parameters:
     ///   - type: Type to decode
     ///   - request: Request to decode from
+    ///   - context: Request context
     public func decode<T: Decodable>(_ type: T.Type, from request: Request, context: some RequestContext) async throws -> T {
         let buffer = try await request.body.collect(upTo: context.maxUploadSize)
         let string = String(buffer: buffer)

Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift

@@ -65,6 +65,7 @@ public struct URLEncodedFormEncoder: Sendable {
     /// - Parameters:
     ///   - dateEncodingStrategy: date encoding strategy
     ///   - userInfo: user info to supply to encoder
+    ///   - additionalKeys: Deprecated variable
     public init(
         dateEncodingStrategy: URLEncodedFormEncoder.DateEncodingStrategy = .deferredToDate,
         userInfo: [CodingUserInfoKey: Sendable] = [:],

Sources/Hummingbird/Exports.swift

@@ -12,14 +12,14 @@
 //
 //===----------------------------------------------------------------------===//
 
-@_exported import struct HummingbirdCore.BindAddress
-@_exported import struct HummingbirdCore.Request
-@_exported import struct HummingbirdCore.RequestBody
-@_exported import struct HummingbirdCore.Response
-@_exported import struct HummingbirdCore.ResponseBody
-@_exported import protocol HummingbirdCore.ResponseBodyWriter
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.BindAddress
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.Request
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.RequestBody
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.Response
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.ResponseBody
+@_exported @_documentation(visibility: internal) import protocol HummingbirdCore.ResponseBodyWriter
 #if canImport(Network)
-@_exported import struct HummingbirdCore.TSTLSOptions
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.TSTLSOptions
 #endif
 
 @_exported @_documentation(visibility: internal) import struct NIOCore.ByteBuffer
@@ -30,8 +30,8 @@
 @_exported @_documentation(visibility: internal) import struct HTTPTypes.HTTPResponse
 
 // Temporary exports of unavailable typealiases
-@_exported import struct HummingbirdCore.HBRequest
-@_exported import struct HummingbirdCore.HBRequestBody
-@_exported import struct HummingbirdCore.HBResponse
-@_exported import struct HummingbirdCore.HBResponseBody
-@_exported import protocol HummingbirdCore.HBResponseBodyWriter
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.HBRequest
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.HBRequestBody
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.HBResponse
+@_exported @_documentation(visibility: internal) import struct HummingbirdCore.HBResponseBody
+@_exported @_documentation(visibility: internal) import protocol HummingbirdCore.HBResponseBodyWriter

Sources/Hummingbird/Files/FileIO.swift

@@ -22,7 +22,7 @@ public struct FileIO: Sendable {
     let fileIO: NonBlockingFileIO
 
     /// Initialize FileIO
-    /// - Parameter application: application using FileIO
+    /// - Parameter threadPool: ThreadPool to use for file operations
     public init(threadPool: NIOThreadPool = .singleton) {
         self.fileIO = .init(threadPool: threadPool)
     }
@@ -73,7 +73,7 @@ public struct FileIO: Sendable {
     /// - Parameters:
     ///   - contents: AsyncSequence of buffers to write.
     ///   - path: Path to write to
-    ///   - logger: Logger
+    ///   - context: Request Context
     public func writeFile<AS: AsyncSequence>(
         contents: AS,
         path: String,
@@ -90,9 +90,9 @@ public struct FileIO: Sendable {
     /// Write contents of buffer to file
     ///
     /// - Parameters:
-    ///   - contents: ByteBuffer to write.
+    ///   - buffer: ByteBuffer to write.
     ///   - path: Path to write to
-    ///   - logger: Logger
+    ///   - context: Request Context
     public func writeFile(
         buffer: ByteBuffer,
         path: String,

Sources/Hummingbird/Files/LocalFileSystem.swift

@@ -80,7 +80,7 @@ public struct LocalFileSystem: FileProvider {
     }
 
     /// Get file attributes
-    /// - Parameter id: FileIdentifier
+    /// - Parameter path: FileIdentifier
     /// - Returns: File attributes
     public func getAttributes(id path: FileIdentifier) async throws -> FileAttributes? {
         do {
@@ -103,7 +103,7 @@ public struct LocalFileSystem: FileProvider {
 
     /// Return a reponse body that will write the file body
     /// - Parameters:
-    ///   - id: FileIdentifier
+    ///   - path: FileIdentifier
     ///   - context: Request context
     /// - Returns: Response body
     public func loadFile(id path: FileIdentifier, context: some RequestContext) async throws -> ResponseBody {
@@ -112,7 +112,7 @@ public struct LocalFileSystem: FileProvider {
 
     /// Return a reponse body that will write a partial file body
     /// - Parameters:
-    ///   - id: FileIdentifier
+    ///   - path: FileIdentifier
     ///   - range: Part of file to return
     ///   - context: Request context
     /// - Returns: Response body

Sources/Hummingbird/HTTP/Cookie.swift

@@ -55,7 +55,6 @@ public struct Cookie: Sendable, CustomStringConvertible {
     ///   - path: The scope of each cookie is limited to a set of paths, controlled by the Path attribute
     ///   - secure: The Secure attribute limits the scope of the cookie to "secure" channels
     ///   - httpOnly: The HttpOnly attribute limits the scope of the cookie to HTTP requests
-    ///   - sameSite: The SameSite attribute lets servers specify whether/when cookies are sent with cross-origin requests
     public init(
         name: String,
         value: String,

Sources/Hummingbird/HTTP/MediaType.swift

@@ -141,8 +141,8 @@ public struct MediaType: Sendable, CustomStringConvertible {
     /// Get media type from a file extension
     /// - Parameter extension: file extension
     /// - Returns: media type
-    public static func getMediaType(forExtension: String) -> MediaType? {
-        return extensionMediaTypeMap[forExtension]
+    public static func getMediaType(forExtension extension: String) -> MediaType? {
+        return extensionMediaTypeMap[`extension`]
     }
 
     /// Media type categories

Sources/Hummingbird/Middleware/FileMiddleware.swift

@@ -78,7 +78,7 @@ public struct FileMiddleware<Context: RequestContext, Provider: FileProvider>: R
     ///   - fileProvider: File provider
     ///   - urlBasePath: Prefix to remove from request URL
     ///   - cacheControl: What cache control headers to include in response
-    ///   - indexHtml: Should we look for index.html in folders
+    ///   - searchForIndexHtml: Should we look for index.html in folders
     public init(
         fileProvider: Provider,
         urlBasePath: String? = nil,

Sources/Hummingbird/Router/RouteCollection.swift

@@ -57,7 +57,9 @@ public final class RouteCollection<Context: RequestContext>: RouterMethods {
 
 extension RouterMethods {
     /// Add route collection to router
-    /// - Parameter collection: Route collection
+    /// - Parameters
+    ///   - collection: Route collection
+    ///   - path: Root path to add routes to
     @discardableResult public func addRoutes(_ collection: RouteCollection<Context>, atPath path: RouterPath = "") -> Self {
         for route in collection.routes {
             // ensure path starts with a "/" and doesn't end with a "/"

Sources/Hummingbird/Router/RouterMethods.swift

@@ -96,7 +96,7 @@ extension RouterMethods {
     /// ```
     /// This gives a slight performance boost over adding them individually.
     ///
-    /// - Parameter middlewareStack: Middleware stack result builder
+    /// - Parameter buildMiddlewareStack: Middleware stack result builder
     /// - Returns: router
     @discardableResult public func addMiddleware(
         @MiddlewareFixedTypeBuilder<Request, Response, Context> buildMiddlewareStack: () -> some MiddlewareProtocol<Request, Response, Context>

Sources/Hummingbird/Router/RouterResponder.swift

@@ -36,8 +36,10 @@ public struct RouterResponder<Context: RequestContext>: HTTPResponder {
     }
 
     /// Respond to request by calling correct handler
-    /// - Parameter request: HTTP request
-    /// - Returns: EventLoopFuture that will be fulfilled with the Response
+    /// - Parameters
+    ///   - request: HTTP request
+    ///   - context: Request context
+    /// - Returns: Response
     @inlinable
     public func respond(to request: Request, context: Context) async throws -> Response {
         do {

Sources/Hummingbird/Server/Request.swift

@@ -29,7 +29,9 @@ extension Request {
     }
 
     /// Decode request using decoder stored at `Application.decoder`.
-    /// - Parameter type: Type you want to decode to
+    /// - Parameters
+    ///   - type: Type you want to decode to
+    ///   - context: Request context
     public func decode<Type: Decodable>(as type: Type.Type, context: some RequestContext) async throws -> Type {
         do {
             return try await context.requestDecoder.decode(type, from: self, context: context)

Sources/Hummingbird/Storage/PersistDriver.swift

@@ -62,7 +62,6 @@ extension PersistDriver {
     /// - Parameters:
     ///   - key: Key to store value against
     ///   - value: Codable value to store
-    ///   - expires: If non-nil defines time that value will expire
     public func set(key: String, value: some Codable & Sendable) async throws {
         try await self.set(key: key, value: value, expires: nil)
     }

Sources/HummingbirdCore/Request/Request.swift

@@ -38,7 +38,6 @@ public struct Request: Sendable {
     /// - Parameters:
     ///   - head: HTTP head
     ///   - body: HTTP body
-    ///   - id: Unique RequestID
     public init(
         head: HTTPRequest,
         body: RequestBody
@@ -54,7 +53,7 @@ public struct Request: Sendable {
     /// you don't need to store the collated ByteBuffer on the request then use
     /// `request.body.collect(maxSize:)`.
     ///
-    /// - Parameter upTo: Maxiumum size of body to collect
+    /// - Parameter maxSize: Maxiumum size of body to collect
     /// - Returns: Collated body
     public mutating func collectBody(upTo maxSize: Int) async throws -> ByteBuffer {
         let byteBuffer = try await self.body.collect(upTo: maxSize)

Sources/HummingbirdCore/Server/HTTP/HTTP1Channel.swift

@@ -60,7 +60,7 @@ public struct HTTP1Channel: ServerChildChannel, HTTPChannelHandler {
 
     /// handle HTTP messages being passed down the channel pipeline
     /// - Parameters:
-    ///   - value: Object to process input/output on child channel
+    ///   - asyncChannel: NIOAsyncChannel handling HTTP parts
     ///   - logger: Logger to use while processing messages
     public func handle(
         value asyncChannel: NIOCore.NIOAsyncChannel<HTTPRequestPart, HTTPResponsePart>,

Sources/HummingbirdRouter/ContextTransform.swift

@@ -38,7 +38,7 @@ public struct ContextTransform<Context: RouterRequestContext, HandlerContext: Ro
 
     /// Create RouteGroup from result builder
     /// - Parameters:
-    ///   - routerPath: Path local to group route this group is defined in
+    ///   - context: RequestContext to convert to
     ///   - builder: RouteGroup builder
     public init(
         to context: HandlerContext.Type,

Sources/HummingbirdRouter/RouterBuilder.swift

@@ -37,6 +37,7 @@ public struct RouterBuilder<Context: RouterRequestContext, Handler: MiddlewarePr
     /// Initialize RouterBuilder with contents of result builder
     /// - Parameters:
     ///   - context: Request context used by router
+    ///   - options: Router options
     ///   - builder: Result builder for router
     public init(
         context: Context.Type = Context.self,

Sources/HummingbirdTesting/Application+Test.swift

@@ -72,8 +72,8 @@ extension ApplicationProtocol {
     /// ```
     ///
     /// - Parameters:
-    ///   - testing: indicates which type of testing framework we want
-    ///   - configuration: configuration of application
+    ///   - testingSetup: indicates which type of testing framework we want
+    ///   - test: test function
     public func test<Value>(
         _ testingSetup: TestingSetup,
         _ test: @escaping @Sendable (any TestClientProtocol) async throws -> Value

Sources/HummingbirdTesting/TestClient.swift

@@ -55,7 +55,7 @@ public struct TestClient: Sendable {
     /// - Parameters:
     ///   - host: host to connect
     ///   - port: port to connect to
-    ///   - tlsConfiguration: TLS configuration if required
+    ///   - configuration: Client configuration
     ///   - eventLoopGroupProvider: EventLoopGroup to use
     public init(
         host: String,