diff --git a/Sources/Hummingbird/Application.swift b/Sources/Hummingbird/Application.swift index 46ca6b67d..fb1ea31bb 100644 --- a/Sources/Hummingbird/Application.swift +++ b/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: ApplicationProtocol where Responder.Context: RequestContext { public typealias Context = Responder.Context public typealias Responder = Responder diff --git a/Sources/Hummingbird/Codable/CodableProtocols.swift b/Sources/Hummingbird/Codable/CodableProtocols.swift index 64bea8674..f88a29ad2 100644 --- a/Sources/Hummingbird/Codable/CodableProtocols.swift +++ b/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: diff --git a/Sources/Hummingbird/Codable/JSON/JSONCoding.swift b/Sources/Hummingbird/Codable/JSON/JSONCoding.swift index f8e35c18f..3ca8091b7 100644 --- a/Sources/Hummingbird/Codable/JSON/JSONCoding.swift +++ b/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(_ 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) diff --git a/Sources/Hummingbird/Codable/ResponseEncodable.swift b/Sources/Hummingbird/Codable/ResponseEncodable.swift index e24628314..c17d7c8fd 100644 --- a/Sources/Hummingbird/Codable/ResponseEncodable.swift +++ b/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) diff --git a/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift b/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift index 908c4fbbf..a915269c4 100644 --- a/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormDecoder.swift +++ b/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) } diff --git a/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift b/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift index 29effd27a..0020e3818 100644 --- a/Sources/Hummingbird/Codable/URLEncodedForm/URLEncodedFormEncoder.swift +++ b/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) } diff --git a/Sources/Hummingbird/Configuration.swift b/Sources/Hummingbird/Configuration.swift index 9beb0551e..1c6716975 100644 --- a/Sources/Hummingbird/Configuration.swift +++ b/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( diff --git a/Sources/Hummingbird/HTTP/Cookies.swift b/Sources/Hummingbird/HTTP/Cookies.swift index faceb4c78..55f326f3d 100644 --- a/Sources/Hummingbird/HTTP/Cookies.swift +++ b/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 diff --git a/Sources/Hummingbird/HTTP/Request+Cookies.swift b/Sources/Hummingbird/HTTP/Request+Cookies.swift index cbdbc0c8b..04531bb41 100644 --- a/Sources/Hummingbird/HTTP/Request+Cookies.swift +++ b/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) } diff --git a/Sources/Hummingbird/HTTP/Response+Cookies.swift b/Sources/Hummingbird/HTTP/Response+Cookies.swift index fa0e782fb..ee59c73b2 100644 --- a/Sources/Hummingbird/HTTP/Response+Cookies.swift +++ b/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) } diff --git a/Sources/Hummingbird/Middleware/CORSMiddleware.swift b/Sources/Hummingbird/Middleware/CORSMiddleware.swift index f90d81324..de61a9588 100644 --- a/Sources/Hummingbird/Middleware/CORSMiddleware.swift +++ b/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 diff --git a/Sources/Hummingbird/Middleware/FileMiddleware.swift b/Sources/Hummingbird/Middleware/FileMiddleware.swift index 6a573ea1c..a08469d64 100644 --- a/Sources/Hummingbird/Middleware/FileMiddleware.swift +++ b/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 Response) async throws -> Response { do { return try await next(request, context) @@ -142,7 +142,7 @@ extension FileMiddleware { case loadFile(HTTPFields, ClosedRange?) } - /// 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), diff --git a/Sources/Hummingbird/Middleware/LogRequestMiddleware.swift b/Sources/Hummingbird/Middleware/LogRequestMiddleware.swift index c4f8024bb..a32e67324 100644 --- a/Sources/Hummingbird/Middleware/LogRequestMiddleware.swift +++ b/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: RouterMiddleware { /// Header filter public struct HeaderFilter: Sendable, ExpressibleByArrayLiteral { diff --git a/Sources/Hummingbird/Middleware/TracingMiddleware.swift b/Sources/Hummingbird/Middleware/TracingMiddleware.swift index 9a39ded5d..eec277e6b 100644 --- a/Sources/Hummingbird/Middleware/TracingMiddleware.swift +++ b/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: 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 = [], 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 diff --git a/Sources/Hummingbird/Router/EndpointResponder.swift b/Sources/Hummingbird/Router/EndpointResponder.swift index b7495e069..556944fd4 100644 --- a/Sources/Hummingbird/Router/EndpointResponder.swift +++ b/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: Sendable { init(path: String) { self.path = path diff --git a/Sources/Hummingbird/Router/Parameters+UUID.swift b/Sources/Hummingbird/Router/Parameters+UUID.swift index feee602be..bd4612f0f 100644 --- a/Sources/Hummingbird/Router/Parameters+UUID.swift +++ b/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 diff --git a/Sources/Hummingbird/Router/ResponseGenerator.swift b/Sources/Hummingbird/Router/ResponseGenerator.swift index 1d3268709..ca4bf424c 100644 --- a/Sources/Hummingbird/Router/ResponseGenerator.swift +++ b/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 diff --git a/Sources/Hummingbird/Router/RouteCollection.swift b/Sources/Hummingbird/Router/RouteCollection.swift index 38de2633c..0b2e95e58 100644 --- a/Sources/Hummingbird/Router/RouteCollection.swift +++ b/Sources/Hummingbird/Router/RouteCollection.swift @@ -22,7 +22,7 @@ public final class RouteCollection: 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: RouterMethods { return .init(path: path, router: self) } - /// Add middleware to RouteCollection + /// Add ``RouterMiddlewares`` to ``RouteCollection`` @discardableResult public func add(middleware: any RouterMiddleware) -> Self { self.middlewares.add(middleware) return self diff --git a/Sources/Hummingbird/Router/Router.swift b/Sources/Hummingbird/Router/Router.swift index c1f85c267..2952cde91 100644 --- a/Sources/Hummingbird/Router/Router.swift +++ b/Sources/Hummingbird/Router/Router.swift @@ -16,12 +16,12 @@ import HTTPTypes import HummingbirdCore import NIOCore -/// Create rules for routing requests and then create `Responder` that will follow these rules. +/// Create rules for routing requests and then create ``HTTPResponder`` that will follow these rules. /// -/// `Router` requires an implementation of the `on(path:method:use)` functions but because it -/// also conforms to `RouterMethods` it is also possible to call the method specific functions `get`, `put`, -/// `head`, `post` and `patch`. The route handler closures all return objects conforming to -/// `ResponseGenerator`. This allows us to support routes which return a multitude of types eg +/// `Router` requires an implementation of the ``on(_:method:use:)`` functions but because it +/// also conforms to `RouterMethods` it is also possible to call the method specific functions ``get(_:use:)``, ``put(_:use:)``, +/// ``head(_:use:)``, ``post(_:use:)`` and ``patch(_:use:)``. The route handler closures all return objects conforming to +/// ``ResponseGenerator``. This allows us to support routes which return a multitude of types eg /// ``` /// router.get("string") { _, _ -> String in /// return "string" @@ -34,14 +34,14 @@ import NIOCore /// } /// ``` /// -/// The default `Router` setup in `Application` is the `TrieRouter` . This uses a -/// trie to partition all the routes for faster access. It also supports wildcards and parameter extraction +/// The default ``Router`` setup in ``Application`` is the ``RouterTrie`` . This uses a +/// trie to partition all the routes for faster access. It also supports wildcards and ``Parameters`` extraction /// ``` /// router.get("user/*", use: anyUser) /// router.get("user/:id", use: userWithId) /// ``` /// Both of these match routes which start with "/user" and the next path segment being anything. -/// The second version extracts the path segment out and adds it to `Request.parameters` with the +/// The second version extracts the path segment out and adds it to ``RequestContext/parameters`` with the /// key "id". public final class Router: RouterMethods, HTTPResponderBuilder { var trie: RouterPathTrieBuilder> @@ -105,14 +105,14 @@ struct NotFoundResponder: HTTPResponder { } } -/// A type that has a single method to build a HTTPResponder +/// A type that has a single method to build a ``HTTPResponder`` public protocol HTTPResponderBuilder { associatedtype Responder: HTTPResponder /// build a responder func buildResponder() -> Responder } -/// Router Options +/// Router Options, allowing customization of router behaviour public struct RouterOptions: OptionSet, Sendable { public let rawValue: Int @@ -122,6 +122,7 @@ public struct RouterOptions: OptionSet, Sendable { /// Router path comparisons will be case insensitive public static var caseInsensitive: Self { .init(rawValue: 1 << 0) } - /// For every GET request that does not have a HEAD request, auto generate the HEAD request + + /// For every GET route that does not have a HEAD route, auto generate the HEAD route public static var autoGenerateHeadEndpoints: Self { .init(rawValue: 1 << 1) } } diff --git a/Sources/Hummingbird/Router/RouterGroup.swift b/Sources/Hummingbird/Router/RouterGroup.swift index 26b45c298..d9474fe45 100644 --- a/Sources/Hummingbird/Router/RouterGroup.swift +++ b/Sources/Hummingbird/Router/RouterGroup.swift @@ -16,10 +16,10 @@ import HTTPTypes import HummingbirdCore import NIOCore -/// Used to group together routes under a single path. Additional middleware can be added to the endpoint and each route can add a +/// Used to group together routes under a single path. Additional ``RouterMiddleware`` can be added to the endpoint and each route can add a /// suffix to the endpoint path /// -/// The code below creates an `RouterGroup`with path "todos" and adds GET and PUT routes on "todos" and adds GET, PUT and +/// The code below creates an ``RouterGroup``with path "todos" and adds GET and PUT routes on "todos" and adds GET, PUT and /// DELETE routes on "todos/:id" where id is the identifier for the todo /// ``` /// app.router @@ -57,7 +57,7 @@ public struct RouterGroup: RouterMethods { ) } - /// Add responder to call when path and method are matched + /// Adds an ``HTTPResponder`` to call when path and method are matched /// /// - Parameters: /// - path: Path to match diff --git a/Sources/Hummingbird/Router/RouterMethods.swift b/Sources/Hummingbird/Router/RouterMethods.swift index b655c851c..81ccdfff8 100644 --- a/Sources/Hummingbird/Router/RouterMethods.swift +++ b/Sources/Hummingbird/Router/RouterMethods.swift @@ -15,7 +15,7 @@ import HTTPTypes import NIOCore -/// Conform to `RouterMethods` to add standard router verb (get, post ...) methods +/// Conform to ``RouterMethods`` to add standard methods for HTTP verbs (get, post ...) public protocol RouterMethods { associatedtype Context: BaseRequestContext @@ -48,7 +48,7 @@ extension RouterMethods { return self } - /// GET path for async closure returning type conforming to ResponseGenerator + /// GET path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func get( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator @@ -56,7 +56,7 @@ extension RouterMethods { return self.on(path, method: .get, use: handler) } - /// PUT path for async closure returning type conforming to ResponseGenerator + /// PUT path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func put( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator @@ -64,7 +64,7 @@ extension RouterMethods { return self.on(path, method: .put, use: handler) } - /// DELETE path for async closure returning type conforming to ResponseGenerator + /// DELETE path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func delete( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator @@ -72,7 +72,7 @@ extension RouterMethods { return self.on(path, method: .delete, use: handler) } - /// HEAD path for async closure returning type conforming to ResponseGenerator + /// HEAD path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func head( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator @@ -80,7 +80,7 @@ extension RouterMethods { return self.on(path, method: .head, use: handler) } - /// POST path for async closure returning type conforming to ResponseGenerator + /// POST path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func post( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator @@ -88,7 +88,7 @@ extension RouterMethods { return self.on(path, method: .post, use: handler) } - /// PATCH path for async closure returning type conforming to ResponseGenerator + /// PATCH path for async closure returning type conforming to ``ResponseGenerator`` @discardableResult public func patch( _ path: String = "", use handler: @Sendable @escaping (Request, Context) async throws -> some ResponseGenerator diff --git a/Sources/Hummingbird/Router/RouterPath.swift b/Sources/Hummingbird/Router/RouterPath.swift index d194845f6..7271e271a 100644 --- a/Sources/Hummingbird/Router/RouterPath.swift +++ b/Sources/Hummingbird/Router/RouterPath.swift @@ -12,8 +12,9 @@ // //===----------------------------------------------------------------------===// -/// Split router path into components +/// An HTTP path, representing a resource, composed of multiple ``RouterPath/Element``s. public struct RouterPath: Sendable, ExpressibleByStringLiteral, CustomStringConvertible { + /// A single path component for matching by a ``Router`` public enum Element: Equatable, Sendable, CustomStringConvertible { case path(Substring) case capture(Substring) diff --git a/Sources/Hummingbird/Router/RouterResponder.swift b/Sources/Hummingbird/Router/RouterResponder.swift index 83945ce33..a9e3cbc3b 100644 --- a/Sources/Hummingbird/Router/RouterResponder.swift +++ b/Sources/Hummingbird/Router/RouterResponder.swift @@ -31,8 +31,9 @@ public struct RouterResponder: HTTPResponder { } /// Respond to request by calling correct handler - /// - Parameter request: HTTP request - /// - Returns: EventLoopFuture that will be fulfilled with the Response + /// - Parameter request: HTTP ``Request`` to respond to + /// - Parameter context: Information about the circumstances of this request, such as authentication or + /// - Returns: The ``Response`` produced in reply to the request. public func respond(to request: Request, context: Context) async throws -> Response { let path: String if self.options.contains(.caseInsensitive) { diff --git a/Sources/Hummingbird/Server/Request.swift b/Sources/Hummingbird/Server/Request.swift index 6195077cb..a0f14c919 100644 --- a/Sources/Hummingbird/Server/Request.swift +++ b/Sources/Hummingbird/Server/Request.swift @@ -15,13 +15,14 @@ import HummingbirdCore extension Request { - /// Collapse body into one ByteBuffer. + /// Collapse body into one ``ByteBuffer``. If the request body is larger than ``BaseRequestContext/maxUploadSize-23mxy``, + /// collating fails and throws an error. /// /// This will store the collated ByteBuffer back into the request so is a mutating method. If /// you don't need to store the collated ByteBuffer on the request then use - /// `request.body.collate(maxSize:)`. + /// `request.body.collect(upTo:)`. /// - /// - Parameter context: request context + /// - Parameter context: The request context. /// - Returns: Collated body public mutating func collateBody(context: some BaseRequestContext) async throws -> ByteBuffer { let byteBuffer = try await self.body.collect(upTo: context.maxUploadSize) @@ -29,8 +30,8 @@ extension Request { return byteBuffer } - /// Decode request using decoder stored at `Application.decoder`. - /// - Parameter type: Type you want to decode to + /// Decode request using ``BaseRequestContext/Decoder`` stored at ``BaseRequestContext/requestDecoder-5yz7o``. + /// - Parameter type: The ``Decodable`` type to decode. public func decode(as type: Type.Type, context: some BaseRequestContext) async throws -> Type { do { return try await context.requestDecoder.decode(type, from: self, context: context) diff --git a/Sources/Hummingbird/Server/RequestContext.swift b/Sources/Hummingbird/Server/RequestContext.swift index 1d77fc236..1706d5053 100644 --- a/Sources/Hummingbird/Server/RequestContext.swift +++ b/Sources/Hummingbird/Server/RequestContext.swift @@ -58,8 +58,9 @@ public struct CoreRequestContext: Sendable { } } -/// Protocol that all request contexts should conform to. Holds data associated with -/// a request. Provides context for request processing +/// Protocol that all request contexts must conform to. Holds data associated with +/// a request. Provides context for request processing, such as the authentication state. Is passed around through +/// ``RouterMiddleware``, which can refine the context with extra information. public protocol BaseRequestContext: Sendable { associatedtype Decoder: RequestDecoder = JSONDecoder associatedtype Encoder: ResponseEncoder = JSONEncoder @@ -78,23 +79,23 @@ public protocol BaseRequestContext: Sendable { extension BaseRequestContext { @inlinable public var allocator: ByteBufferAllocator { coreContext.allocator } - /// Logger to use with Request + /// ``Logger`` to use with ``Request`` @inlinable public var logger: Logger { get { coreContext.logger } set { coreContext.logger = newValue } } - /// maxUploadSize + /// The maximum amount of bytes that a user is allowed to upload through a ``RequestBody``. @inlinable public var maxUploadSize: Int { 2 * 1024 * 1024 } /// Endpoint path @inlinable public var endpointPath: String? { coreContext.endpointPath.value } - /// Parameters extracted from URI + /// Parameters extracted from ``URI`` @inlinable public var parameters: Parameters { coreContext.parameters } - /// Request ID, extracted from Logger + /// Request ID, extracted from ``Logger`` @inlinable public var id: String { self.logger[metadataKey: "hb_id"]!.description } } @@ -124,7 +125,7 @@ public protocol RequestContext: BaseRequestContext { init(channel: Channel, logger: Logger) } -/// Implementation of a basic request context that supports everything the Hummingbird library needs +/// Implementation of a ``RequestContext`` that supports everything the Hummingbird library needs, but doesn't add any additional information. public struct BasicRequestContext: RequestContext { /// core context public var coreContext: CoreRequestContext diff --git a/Sources/Hummingbird/Server/RequestID.swift b/Sources/Hummingbird/Server/RequestID.swift index 9c17bd183..9f1a8932c 100644 --- a/Sources/Hummingbird/Server/RequestID.swift +++ b/Sources/Hummingbird/Server/RequestID.swift @@ -14,7 +14,7 @@ import Atomics -/// Generate Unique ID for each request +/// A Unique ID, generated for each request. public struct RequestID: CustomStringConvertible, Sendable { let low: UInt64 diff --git a/Sources/Hummingbird/Storage/PersistDriver.swift b/Sources/Hummingbird/Storage/PersistDriver.swift index fffbfe5f0..aa310d8bd 100644 --- a/Sources/Hummingbird/Storage/PersistDriver.swift +++ b/Sources/Hummingbird/Storage/PersistDriver.swift @@ -47,10 +47,10 @@ public protocol PersistDriver: Service { } extension PersistDriver { - /// default implemenation of shutdown() + /// Default implemenation of shutdown() public func shutdown() async throws {} - /// create key/value pair. If key already exist throw `PersistError.duplicate` error + /// Creates a key/value pair. If key already exist throw `PersistError.duplicate` error /// - Parameters: /// - key: Key to store value against /// - value: Codable value to store @@ -58,7 +58,7 @@ extension PersistDriver { try await self.create(key: key, value: value, expires: nil) } - /// set value for key. If value already exists overwrite it + /// Set value for key. If value already exists overwrite it /// - Parameters: /// - key: Key to store value against /// - value: Codable value to store diff --git a/Sources/HummingbirdCore/Error/HTTPError.swift b/Sources/HummingbirdCore/Error/HTTPError.swift index 97a0e7dd2..f81a8f2de 100644 --- a/Sources/HummingbirdCore/Error/HTTPError.swift +++ b/Sources/HummingbirdCore/Error/HTTPError.swift @@ -31,7 +31,7 @@ public struct HTTPError: Error, HTTPResponseError, Sendable { } } - /// error message + /// Error message public var body: String? /// Initialize HTTPError diff --git a/Sources/HummingbirdCore/Request/Request.swift b/Sources/HummingbirdCore/Request/Request.swift index f1cb914b1..d5a3323f7 100644 --- a/Sources/HummingbirdCore/Request/Request.swift +++ b/Sources/HummingbirdCore/Request/Request.swift @@ -14,7 +14,7 @@ import HTTPTypes -/// Holds all the values required to process a request +/// Holds all the values required to process an HTTP request. public struct Request: Sendable { // MARK: Member variables @@ -22,11 +22,11 @@ public struct Request: Sendable { public let uri: URI /// HTTP head public let head: HTTPRequest - /// Body of HTTP request + /// The body of HTTP request, which defaults to streaming. public var body: RequestBody - /// Request HTTP method + /// Request HTTP method, indicates the desired action to be performed for a given resource. public var method: HTTPRequest.Method { self.head.method } - /// Request HTTP headers + /// Request HTTP headers. These headers contain additional metadata about a ``Request``. Examples include the ``MediaType`` of a body, the body's (content-)length and proof of authorization. public var headers: HTTPFields { self.head.headerFields } // MARK: Initialization @@ -35,7 +35,6 @@ public struct Request: Sendable { /// - Parameters: /// - head: HTTP head /// - body: HTTP body - /// - id: Unique RequestID public init( head: HTTPRequest, body: RequestBody diff --git a/Sources/HummingbirdCore/Request/RequestBody.swift b/Sources/HummingbirdCore/Request/RequestBody.swift index fe1315260..56369fa43 100644 --- a/Sources/HummingbirdCore/Request/RequestBody.swift +++ b/Sources/HummingbirdCore/Request/RequestBody.swift @@ -17,9 +17,9 @@ import NIOConcurrencyHelpers import NIOCore import NIOHTTPTypes -/// Request Body +/// The body of an HTTP ``Request``. /// -/// Can be either a stream of ByteBuffers or a single ByteBuffer +/// This can be represented as one ``ByteBuffer`` or a stream of ByteBuffers. The default Hummingbird HTTP ``Server``s start out by representing bodies as a stream. public struct RequestBody: Sendable, AsyncSequence { @usableFromInline internal enum _Backing: Sendable { @@ -49,7 +49,7 @@ public struct RequestBody: Sendable, AsyncSequence { } } -/// AsyncSequence protocol requirements +/// ``AsyncSequence`` protocol requirements. extension RequestBody { public typealias Element = ByteBuffer @@ -79,7 +79,7 @@ extension RequestBody { } } -/// Extend RequestBody to create request body streams backed by `NIOThrowingAsyncSequenceProducer`. +/// Extend ``RequestBody`` to create request body streams backed by ``NIOThrowingAsyncSequenceProducer``. extension RequestBody { @usableFromInline typealias Producer = NIOThrowingAsyncSequenceProducer< @@ -143,7 +143,7 @@ extension RequestBody { self.waitForProduceMore = .init(false) } - /// Yields the element to the inbound stream. + /// Yields the element, to the inbound stream. /// /// This function implements back pressure in that it will wait if the producer /// sequence indicates the Source should produce more ByteBuffers. @@ -163,13 +163,13 @@ extension RequestBody { } } - /// Finished the inbound stream. + /// Finishes the inbound stream. @inlinable public func finish() { self.source.finish() } - /// Finished the inbound stream. + /// Finishes the inbound stream with an error. /// /// - Parameter error: The error to throw @inlinable @@ -179,7 +179,7 @@ extension RequestBody { } /// Make a new ``RequestBody`` stream - /// - Returns: The new `RequestBody` and a source to yield ByteBuffers to the `RequestBody`. + /// - Returns: The new ``RequestBody`` and a source to yield ByteBuffers to the ``RequestBody``. @inlinable public static func makeStream() -> (RequestBody, Source) { let delegate = Delegate() @@ -192,7 +192,7 @@ extension RequestBody { } } -/// Request body that is a stream of ByteBuffers sourced from a NIOAsyncChannelInboundStream. +/// ``RequestBody`` that is a stream of ``ByteBuffer``s sourced from a ``NIOAsyncChannelInboundStream``. /// /// This is a unicast async sequence that allows a single iterator to be created. @usableFromInline @@ -260,7 +260,7 @@ final class NIOAsyncChannelRequestBody: Sendable, AsyncSequence { } } -/// Request body stream that is a single ByteBuffer +/// Request body stream that is a single ``ByteBuffer`` /// /// This is used when converting a ByteBuffer back to a stream of ByteBuffers @usableFromInline diff --git a/Sources/HummingbirdCore/Server/Server.swift b/Sources/HummingbirdCore/Server/Server.swift index a3d758f7c..4383c532d 100644 --- a/Sources/HummingbirdCore/Server/Server.swift +++ b/Sources/HummingbirdCore/Server/Server.swift @@ -287,14 +287,14 @@ protocol ServerBootstrapProtocol { ) async throws -> NIOAsyncChannel } -// Extend both `ServerBootstrap` and `NIOTSListenerBootstrap` to conform to `ServerBootstrapProtocol` +/// Extend both ``ServerBootstrap`` and ``NIOTSListenerBootstrap`` to conform to ``ServerBootstrapProtocol`` extension ServerBootstrap: ServerBootstrapProtocol {} #if canImport(Network) @available(macOS 10.14, iOS 12, tvOS 12, *) extension NIOTSListenerBootstrap: ServerBootstrapProtocol { - // need to be able to extend `NIOTSListenerBootstrap` to conform to `ServerBootstrapProtocol` - // before we can use TransportServices + /// need to be able to extend ``NIOTSListenerBootstrap`` to conform to ``ServerBootstrapProtocol`` + /// before we can use TransportServices func bind( unixDomainSocketPath: String, cleanupExistingSocketFile: Bool, diff --git a/Sources/HummingbirdCore/Server/ServerChildChannel.swift b/Sources/HummingbirdCore/Server/ServerChildChannel.swift index 3654731f4..36fab7b12 100644 --- a/Sources/HummingbirdCore/Server/ServerChildChannel.swift +++ b/Sources/HummingbirdCore/Server/ServerChildChannel.swift @@ -16,7 +16,7 @@ import Logging import NIOCore import ServiceLifecycle -/// HTTPServer child channel setup protocol +/// HTTP ``Server`` child channel setup protocol public protocol ServerChildChannel: Sendable { associatedtype Value: Sendable diff --git a/Sources/HummingbirdCore/Server/ServerConfiguration.swift b/Sources/HummingbirdCore/Server/ServerConfiguration.swift index ae93a59fe..4c484efdb 100644 --- a/Sources/HummingbirdCore/Server/ServerConfiguration.swift +++ b/Sources/HummingbirdCore/Server/ServerConfiguration.swift @@ -14,7 +14,7 @@ import NIOCore -/// HTTP server configuration +/// An HTTP ``Server``'s configuration public struct ServerConfiguration: Sendable { /// Bind address for server public let address: Address diff --git a/Sources/HummingbirdJobs/Utils/DecodableWithUserInfoConfiguration.swift b/Sources/HummingbirdJobs/Utils/DecodableWithUserInfoConfiguration.swift index 9747de690..f2fb6f0bf 100644 --- a/Sources/HummingbirdJobs/Utils/DecodableWithUserInfoConfiguration.swift +++ b/Sources/HummingbirdJobs/Utils/DecodableWithUserInfoConfiguration.swift @@ -33,13 +33,12 @@ extension DecodableWithUserInfoConfiguration { } extension CodingUserInfoKey { - /// Coding UserInfo key used to store DecodableWithUserInfoConfiguration configuration + /// ``CodingUserInfo`` key used to store ``DecodableWithUserInfoConfiguration`` configuration static var configuration: Self { return .init(rawValue: "_configuration_")! } } extension JSONDecoder { - /// Version of JSONDecoder that sets up configuration userInfo for the DecodableWithUserInfoConfiguration - /// protocol + /// Version of ``JSONDecoder`` that sets up configuration userInfo for the ``DecodableWithUserInfoConfiguration`` protocol func decode( _ type: T.Type, from buffer: ByteBuffer,