Fix up some old docs and add more DocC annotations

Sources/Hummingbird/Application.swift

@@ -144,7 +144,7 @@ extension ApplicationProtocol {
     }
 }
 
-/// Application class. Brings together all the components of Hummingbird together
+/// A Web Application. Brings together all the components of Hummingbird together.
 ///
 /// ```
 /// let router = Router()
@@ -155,7 +155,7 @@ extension ApplicationProtocol {
 /// let app = Application(responder: router.buildResponder())
 /// try await app.runService()
 /// ```
-/// Editing the application setup after calling `runService` will produce undefined behaviour.
+/// Editing the application setup after calling ``runService`` will produce undefined behaviour.
 public struct Application<Responder: HTTPResponder>: ApplicationProtocol where Responder.Context: RequestContext {
     public typealias Context = Responder.Context
     public typealias Responder = Responder

Sources/Hummingbird/Codable/CodableProtocols.swift

@@ -14,7 +14,7 @@
 
 import HTTPTypes
 
-/// protocol for encoders generating a Response
+/// Protocol for ``Encoder``s  that generate a ``Response``
 public protocol ResponseEncoder {
     /// Encode value returned by handler to request
     ///
@@ -24,7 +24,7 @@ public protocol ResponseEncoder {
     func encode(_ value: some Encodable, from request: Request, context: some BaseRequestContext) throws -> Response
 }
 
-/// protocol for decoder deserializing from a Request body
+/// Protocol for ``Decoder``s deserializing from a ``Request``'s body
 public protocol RequestDecoder {
     /// Decode type from request
     /// - Parameters:

Sources/Hummingbird/Codable/JSON/JSONCoding.swift

@@ -18,10 +18,10 @@ import struct Foundation.Date
 import NIOFoundationCompat
 
 extension JSONEncoder: ResponseEncoder {
-    /// Extend JSONEncoder to support encoding `Response`'s. Sets body and header values
+    /// Extend ``JSONEncoder`` to support encoding ``Response``'s. Sets the ``ResponseBody`` and ``HTTPFields``
     /// - Parameters:
     ///   - value: Value to encode
-    ///   - request: Request used to generate response
+    ///   - request: ``Request`` used to generate the ``Response``
     public func encode(_ value: some Encodable, from request: Request, context: some BaseRequestContext) throws -> Response {
         var buffer = context.allocator.buffer(capacity: 0)
         let data = try self.encode(value)
@@ -35,17 +35,17 @@ extension JSONEncoder: ResponseEncoder {
 }
 
 extension JSONDecoder: RequestDecoder {
-    /// Extend JSONDecoder to decode from `Request`.
+    /// Extend ``JSONDecoder`` to decode from ``Request``.
     /// - Parameters:
-    ///   - type: Type to decode
-    ///   - request: Request to decode from
+    ///   - type: ``Decodable`` type  to decode
+    ///   - request: ``Request`` to decode from
     public func decode<T: Decodable>(_ type: T.Type, from request: Request, context: some BaseRequestContext) async throws -> T {
         let buffer = try await request.body.collect(upTo: context.maxUploadSize)
         return try self.decode(T.self, from: buffer)
     }
 }
 
-/// `RequestDecoder` and `ResponseEncoder` both require conformance to `Sendable`. Given
+/// ``RequestDecoder`` and ``ResponseEncoder`` both require conformance to `Sendable`. Given
 /// `JSONEncoder`` and `JSONDecoder`` conform to Sendable in macOS 13+ I think I can just
 /// back date the conformance to all versions of Swift, macOS we support
 #if hasFeature(RetroactiveAttribute)

Sources/Hummingbird/Codable/ResponseEncodable.swift

@@ -14,34 +14,34 @@
 
 import HummingbirdCore
 
-/// Protocol for encodable object that can generate a response. The router will encode
-/// the response using the encoder stored in `Application.encoder`.
+/// Protocol for ``Encodable`` object that can generate a ``Response``. The router will encode
+/// the response using the ``ResponseEncoder`` stored in ``BaseRequestContext/responseEncoder-90wnm``.
 public protocol ResponseEncodable: Encodable, ResponseGenerator {}
 
-/// Protocol for codable object that can generate a response
+/// Protocol for ``Codable`` object that can generate a ``Response``
 public protocol ResponseCodable: ResponseEncodable, Decodable {}
 
-/// Extend ResponseEncodable to conform to ResponseGenerator
+/// Extend ``ResponseEncodable`` to conform to ``ResponseGenerator``
 extension ResponseEncodable {
     public func response(from request: Request, context: some BaseRequestContext) throws -> Response {
         return try context.responseEncoder.encode(self, from: request, context: context)
     }
 }
 
-/// Extend Array to conform to ResponseGenerator
+/// Extend Array to conform to ``ResponseGenerator``
 extension Array: ResponseGenerator where Element: Encodable {}
 
-/// Extend Array to conform to ResponseEncodable
+/// Extend Array to conform to ``ResponseEncodable``
 extension Array: ResponseEncodable where Element: Encodable {
     public func response(from request: Request, context: some BaseRequestContext) throws -> Response {
         return try context.responseEncoder.encode(self, from: request, context: context)
     }
 }
 
-/// Extend Dictionary to conform to ResponseGenerator
+/// Extend Dictionary to conform to ``ResponseGenerator``
 extension Dictionary: ResponseGenerator where Key: Encodable, Value: Encodable {}
 
-/// Extend Array to conform to ResponseEncodable
+/// Extend Array to conform to ``ResponseEncodable``
 extension Dictionary: ResponseEncodable where Key: Encodable, Value: Encodable {
     public func response(from request: Request, context: some BaseRequestContext) throws -> Response {
         return try context.responseEncoder.encode(self, from: request, context: context)

Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift

@@ -22,23 +22,23 @@ import Foundation
 public struct URLEncodedFormDecoder: Sendable {
     /// The strategy to use for decoding `Date` values.
     public enum DateDecodingStrategy: Sendable {
-        /// Defer to `Date` for decoding. This is the default strategy.
+        /// Defer to ``Date`` for decoding. This is the default strategy.
         case deferredToDate
 
-        /// Decode the `Date` as a UNIX timestamp from a JSON number.
+        /// Decode the ``Date`` as a UNIX timestamp from a JSON number.
         case secondsSince1970
 
-        /// Decode the `Date` as UNIX millisecond timestamp from a JSON number.
+        /// Decode the ``Date`` as UNIX millisecond timestamp from a JSON number.
         case millisecondsSince1970
 
-        /// Decode the `Date` as an ISO-8601-formatted string (in RFC 3339 format).
+        /// Decode the ``Date`` as an ISO-8601-formatted string (in RFC 3339 format).
         @available(macOS 10.12, iOS 10.0, watchOS 3.0, tvOS 10.0, *)
         case iso8601
 
-        /// Decode the `Date` as a string parsed by the given formatter.
+        /// Decode the ``Date`` as a string parsed by the given ``DateFormatter``.
         case formatted(DateFormatter)
 
-        /// Decode the `Date` as a custom value encoded by the given closure.
+        /// Decode the ``Date`` as a custom value encoded by the given closure.
         case custom(@Sendable (_ decoder: Decoder) throws -> Date)
     }
 

Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift

@@ -20,25 +20,25 @@ import Foundation
 
 /// The wrapper struct for encoding Codable classes to URL encoded form data
 public struct URLEncodedFormEncoder: Sendable {
-    /// The strategy to use for encoding `Date` values.
+    /// The strategy to use for encoding ``Date`` values.
     public enum DateEncodingStrategy: Sendable {
-        /// Defer to `Date` for encoding. This is the default strategy.
+        /// Defer to ``Date`` for encoding. This is the default strategy.
         case deferredToDate
 
-        /// Encode the `Date` as a UNIX timestamp from a JSON number.
+        /// Encode the ``Date`` as a UNIX timestamp from a JSON number.
         case secondsSince1970
 
-        /// Encode the `Date` as UNIX millisecond timestamp from a JSON number.
+        /// Encode the ``Date`` as UNIX millisecond timestamp from a JSON number.
         case millisecondsSince1970
 
-        /// Encode the `Date` as an ISO-8601-formatted string (in RFC 3339 format).
+        /// Encode the ``Date`` as an ISO-8601-formatted string (in RFC 3339 format).
         @available(macOS 10.12, iOS 10.0, watchOS 3.0, tvOS 10.0, *)
         case iso8601
 
-        /// Encode the `Date` as a string parsed by the given formatter.
+        /// Encode the ``Date`` as a string parsed by the given ``DateFormatter``.
         case formatted(DateFormatter)
 
-        /// Encode the `Date` as a custom value encoded by the given closure.
+        /// Encode the ``Date`` as a custom value encoded by the given closure.
         case custom(@Sendable (Date, Encoder) throws -> Void)
     }
 

Sources/Hummingbird/Configuration.swift

@@ -21,7 +21,7 @@ import Network
 
 // MARK: Configuration
 
-/// Application configuration
+/// The configuration for Hummingbird's HTTP ``Server``
 public struct ApplicationConfiguration: Sendable {
     // MARK: Member variables
 
@@ -101,7 +101,7 @@ public struct ApplicationConfiguration: Sendable {
         )
     }
 
-    /// return HTTP server configuration
+    /// Return HTTP ``ServerConfiguration``
     #if canImport(Network)
     var httpServer: ServerConfiguration {
         return .init(

Sources/Hummingbird/HTTP/Cookies.swift

@@ -12,9 +12,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Structure holding an array of cookies
+/// Structure holding an array of ``Cookie``s
 ///
-/// Cookies can be accessed from request via `Request.cookies`.
+/// Cookies can be accessed from request via ``Request/cookies``.
 public struct Cookies: Sendable {
     /// Construct cookies accessor from `Request`
     /// - Parameter request: request to get cookies from

Sources/Hummingbird/HTTP/Request+Cookies.swift

@@ -15,7 +15,7 @@
 import HummingbirdCore
 
 extension Request {
-    /// access cookies from request. When accessing this for the first time the Cookies struct will be created
+    /// Access ``Cookies`` from a ``Request``.
     public var cookies: Cookies {
         Cookies(from: self)
     }

Sources/Hummingbird/HTTP/Response+Cookies.swift

@@ -15,16 +15,14 @@
 import HummingbirdCore
 
 extension Response {
-    /// Set cookie on response
+    /// Sets a ``Cookie`` on the ``Response``
     public mutating func setCookie(_ cookie: Cookie) {
         self.headers[values: .setCookie].append(cookie.description)
     }
 }
 
 extension EditedResponse {
-    /// Set cookie on reponse patch
-    ///
-    /// Can be accessed via `request.response.setCookie(myCookie)`
+    /// Set ``Cookie`` on an ``EditedResponse``
     public mutating func setCookie(_ cookie: Cookie) {
         self.headers[values: .setCookie].append(cookie.description)
     }

Sources/Hummingbird/Middleware/CORSMiddleware.swift

@@ -15,7 +15,7 @@
 import HTTPTypes
 import NIOCore
 
-/// Middleware implementing Cross-Origin Resource Sharing (CORS) headers.
+/// ``RouterMiddleware`` implementing Cross-Origin Resource Sharing (CORS) headers.
 ///
 /// If request has "origin" header then generate CORS headers. If method is OPTIONS
 /// then return an empty body with all the standard CORS headers otherwise send

Sources/Hummingbird/Middleware/FileMiddleware.swift

@@ -21,7 +21,7 @@ import NIOPosix
 
 /// Protocol for all the file attributes required by ``FileMiddleware``
 ///
-/// Requirements for the FileAttributes  of the ``FileProvider`` you use with your FileMiddleware
+/// Requirements for the FileAttributes  of the ``FileProvider`` you use with your ``FileMiddleware``
 public protocol FileMiddlewareFileAttributes {
     /// Is file a folder
     var isFolder: Bool { get }
@@ -31,7 +31,7 @@ public protocol FileMiddlewareFileAttributes {
     var modificationDate: Date { get }
 }
 
-/// Middleware for serving static files.
+/// ``RouterMiddleware`` for serving static files.
 ///
 /// If router returns a 404 ie a route was not found then this middleware will treat the request
 /// path as a filename relative to a defined rootFolder (this defaults to "public"). It checks to see if
@@ -84,7 +84,7 @@ public struct FileMiddleware<Context: BaseRequestContext, Provider: FileProvider
         self.fileProvider = fileProvider
     }
 
-    /// Handle request
+    /// Handles a ``Request``
     public func handle(_ request: Request, context: Context, next: (Request, Context) async throws -> Response) async throws -> Response {
         do {
             return try await next(request, context)
@@ -142,7 +142,7 @@ extension FileMiddleware {
         case loadFile(HTTPFields, ClosedRange<Int>?)
     }
 
-    /// Return file attributes, and actual file path
+    /// Return ``FileProvider/FileAttributes``, and actual file path
     private func getFileAttributes(path: String) async throws -> (path: String, attributes: Provider.FileAttributes) {
         guard let attributes = try await self.fileProvider.getAttributes(path: path) else {
             throw HTTPError(.notFound)
@@ -161,7 +161,7 @@ extension FileMiddleware {
         }
     }
 
-    /// Parse request headers and generate response headers
+    /// Parse a ``Request``'s ``HTTPFields`` and generate  the``Response`` headers
     private func constructResponse(path: String, attributes: Provider.FileAttributes, request: Request) async throws -> FileResult {
         let eTag = self.createETag([
             String(describing: attributes.modificationDate.timeIntervalSince1970),

Sources/Hummingbird/Middleware/LogRequestMiddleware.swift

@@ -15,7 +15,7 @@
 import HTTPTypes
 import Logging
 
-/// Middleware outputting to log for every call to server
+/// ``RouterMiddleware`` outputting every call to server as a log using ``BaseRequestContext/logger``
 public struct LogRequestsMiddleware<Context: BaseRequestContext>: RouterMiddleware {
     /// Header filter
     public struct HeaderFilter: Sendable, ExpressibleByArrayLiteral {

Sources/Hummingbird/Middleware/TracingMiddleware.swift

@@ -16,9 +16,9 @@ import HTTPTypes
 import NIOCore
 import Tracing
 
-/// Middleware creating Distributed Tracing spans for each request.
+/// ``RouterMiddleware`` creating Distributed Tracing spans for each request.
 ///
-/// Creates a span for each request, including attributes such as the HTTP method.
+/// Creates a ``Span`` for each request, including attributes such as the HTTP method.
 ///
 /// You may opt in to recording a specific subset of HTTP request/response header values by passing
 /// a set of header names.
@@ -32,7 +32,7 @@ public struct TracingMiddleware<Context: BaseRequestContext>: RouterMiddleware {
     /// - Parameters
     ///     - recordingHeaders: A list of HTTP header names to be recorded as span attributes. By default, no headers
     ///         are being recorded.
-    ///     - parameters: A list of static parameters added to every span. These could be the "net.host.name",
+    ///     - attributes: A list of static attributes added to every span. These could be the "net.host.name",
     ///         "net.host.port" or "http.scheme"
     public init(recordingHeaders headerNamesToRecord: some Collection<HTTPField.Name> = [], attributes: SpanAttributes? = nil) {
         self.headerNamesToRecord = Set(headerNamesToRecord.map(RecordingHeader.init))
@@ -144,7 +144,7 @@ private class SpanWrapper {
     }
 }
 
-/// ``UnsafeTransfer`` can be used to make non-`Sendable` values `Sendable`.
+/// ``UnsafeTransfer`` can be used to make non-``Sendable`` values ``Sendable``.
 /// As the name implies, the usage of this is unsafe because it disables the sendable checking of the compiler.
 /// It can be used similar to `@unsafe Sendable` but for values instead of types.
 @usableFromInline
@@ -187,7 +187,7 @@ private struct HTTPHeadersExtractor: Extractor {
 }
 
 extension Span {
-    /// Update Span attributes in a block instead of individually
+    /// Update ``Span`` attributes in a block instead of individually
     ///
     /// Updating a span attribute will involve some type of thread synchronisation
     /// primitive to avoid multiple threads updating the attributes at the same

Sources/Hummingbird/Router/EndpointResponder.swift

@@ -14,7 +14,7 @@
 
 import HTTPTypes
 
-/// Stores endpoint responders for each HTTP method
+/// Stores an endpoint ``HTTPResponder`` for each HTTP method
 struct EndpointResponders<Context: BaseRequestContext>: Sendable {
     init(path: String) {
         self.path = path

Sources/Hummingbird/Router/Parameters+UUID.swift

@@ -14,7 +14,7 @@
 
 import Foundation
 
-/// It is common for UUID's to be passed in as parameters. So lets add helper
+/// It is common for ``UUID``'s to be passed in as parameters. So lets add helper
 /// functions to extract them from Parameters
 extension Parameters {
     /// Return parameter with specified id as a certain type

Sources/Hummingbird/Router/ResponseGenerator.swift

@@ -14,9 +14,9 @@
 
 import HTTPTypes
 
-/// Object that can generate a `Response`.
+/// Object that can generate a ``Response``.
 ///
-/// This is used by `Router` to convert handler return values into a `Response`.
+/// This is used by ``Router`` to convert handler return values into a ``Response``.
 public protocol ResponseGenerator {
     /// Generate response based on the request this object came from
     func response(from request: Request, context: some BaseRequestContext) throws -> Response

Sources/Hummingbird/Router/RouteCollection.swift

@@ -22,7 +22,7 @@ public final class RouteCollection<Context: BaseRequestContext>: RouterMethods {
         self.middlewares = .init()
     }
 
-    /// Add responder to call when path and method are matched
+    /// Add ``HTTPResponder`` to call when path and method are matched
     ///
     /// - Parameters:
     ///   - path: Path to match
@@ -45,7 +45,7 @@ public final class RouteCollection<Context: BaseRequestContext>: RouterMethods {
         return .init(path: path, router: self)
     }
 
-    /// Add middleware to RouteCollection
+    /// Add ``RouterMiddlewares`` to ``RouteCollection``
     @discardableResult public func add(middleware: any RouterMiddleware<Context>) -> Self {
         self.middlewares.add(middleware)
         return self