diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index c1ac0581f3..90d4e42367 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -10,8 +10,6 @@ jobs: uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main with: license_header_check_project_name: "SwiftNIO" - # We need to move to 6.0 here but have to fix the new warnings first - docs_check_container_image: "swift:5.10-noble" unit-tests: name: Unit tests diff --git a/Sources/NIOAsyncAwaitDemo/FullRequestResponse.swift b/Sources/NIOAsyncAwaitDemo/FullRequestResponse.swift index f0d03ac61d..7b7a9fcbff 100644 --- a/Sources/NIOAsyncAwaitDemo/FullRequestResponse.swift +++ b/Sources/NIOAsyncAwaitDemo/FullRequestResponse.swift @@ -65,7 +65,7 @@ public final class RequestResponseHandler: ChannelDuplexHandl /// Create a new `RequestResponseHandler`. /// - /// - parameters: + /// - Parameters: /// - initialBufferCapacity: `RequestResponseHandler` saves the promises for all outstanding responses in a /// buffer. `initialBufferCapacity` is the initial capacity for this buffer. You usually do not need to set /// this parameter unless you intend to pipeline very deeply and don't want the buffer to resize. diff --git a/Sources/NIOConcurrencyHelpers/NIOLock.swift b/Sources/NIOConcurrencyHelpers/NIOLock.swift index 70e64a97ce..25b0d1b612 100644 --- a/Sources/NIOConcurrencyHelpers/NIOLock.swift +++ b/Sources/NIOConcurrencyHelpers/NIOLock.swift @@ -189,7 +189,7 @@ extension LockStorage: @unchecked Sendable {} /// A threading lock based on `libpthread` instead of `libdispatch`. /// -/// - note: ``NIOLock`` has reference semantics. +/// - Note: ``NIOLock`` has reference semantics. /// /// This object provides a lock on top of a single `pthread_mutex_t`. This kind /// of lock is safe to use with `libpthread`-based threading models, such as the diff --git a/Sources/NIOConcurrencyHelpers/NIOLockedValueBox.swift b/Sources/NIOConcurrencyHelpers/NIOLockedValueBox.swift index dc5916b6dd..f13a9d9e6b 100644 --- a/Sources/NIOConcurrencyHelpers/NIOLockedValueBox.swift +++ b/Sources/NIOConcurrencyHelpers/NIOLockedValueBox.swift @@ -14,7 +14,7 @@ /// Provides locked access to `Value`. /// -/// - note: ``NIOLockedValueBox`` has reference semantics and holds the `Value` +/// - Note: ``NIOLockedValueBox`` has reference semantics and holds the `Value` /// alongside a lock behind a reference. /// /// This is no different than creating a ``Lock`` and protecting all diff --git a/Sources/NIOCore/AsyncAwaitSupport.swift b/Sources/NIOCore/AsyncAwaitSupport.swift index 91e2c2418e..5152728c0d 100644 --- a/Sources/NIOCore/AsyncAwaitSupport.swift +++ b/Sources/NIOCore/AsyncAwaitSupport.swift @@ -58,9 +58,9 @@ extension EventLoopPromise { /// /// This function can be used to bridge the `async` world into an `EventLoopPromise`. /// - /// - parameters: + /// - Parameters: /// - body: The `async` function to run. - /// - returns: A `Task` which was created to `await` the `body`. + /// - Returns: A `Task` which was created to `await` the `body`. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @discardableResult @preconcurrency @@ -82,18 +82,19 @@ extension EventLoopPromise { extension Channel { /// Shortcut for calling `write` and `flush`. /// - /// - parameters: - /// - data: the data to write - /// - promise: the `EventLoopPromise` that will be notified once the `write` operation completes, - /// or `nil` if not interested in the outcome of the operation. + /// - Parameters: + /// - data: the data to write @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @inlinable @preconcurrency - public func writeAndFlush(_ any: T) async throws { - try await self.writeAndFlush(any).get() + public func writeAndFlush(_ data: T) async throws { + try await self.writeAndFlush(data).get() } /// Set `option` to `value` on this `Channel`. + /// - Parameters: + /// - option: The option to set. + /// - value: The new value of the option. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @inlinable public func setOption(_ option: Option, value: Option.Value) async throws { @@ -101,6 +102,8 @@ extension Channel { } /// Get the value of `option` for this `Channel`. + /// - Parameter option: The option to get. + /// - Returns: The value of the option. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @inlinable public func getOption(_ option: Option) async throws -> Option.Value { @@ -110,26 +113,29 @@ extension Channel { extension ChannelOutboundInvoker { /// Register on an `EventLoop` and so have all its IO handled. - /// - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func register(file: StaticString = #fileID, line: UInt = #line) async throws { try await self.register(file: file, line: line).get() } /// Bind to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should bind the `Channel`. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - address: the `SocketAddress` to which we should bind the `Channel`. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func bind(to address: SocketAddress, file: StaticString = #fileID, line: UInt = #line) async throws { try await self.bind(to: address, file: file, line: line).get() } /// Connect to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should connect the `Channel`. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - address: the `SocketAddress` to which we should connect the `Channel`. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func connect(to address: SocketAddress, file: StaticString = #fileID, line: UInt = #line) async throws { try await self.connect(to: address, file: file, line: line).get() @@ -137,9 +143,10 @@ extension ChannelOutboundInvoker { /// Shortcut for calling `write` and `flush`. /// - /// - parameters: - /// - data: the data to write - /// - returns: the future which will be notified once the `write` operation completes. + /// - Parameters: + /// - data: the data to write + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @available( *, @@ -152,9 +159,10 @@ extension ChannelOutboundInvoker { /// Close the `Channel` and so the connection if one exists. /// - /// - parameters: - /// - mode: the `CloseMode` that is used - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - mode: the `CloseMode` that is used + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func close(mode: CloseMode = .all, file: StaticString = #fileID, line: UInt = #line) async throws { try await self.close(mode: mode, file: file, line: line).get() @@ -162,9 +170,10 @@ extension ChannelOutboundInvoker { /// Trigger a custom user outbound event which will flow through the `ChannelPipeline`. /// - /// - parameters: - /// - event: the event itself. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - event: the event itself. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @preconcurrency @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func triggerUserOutboundEvent( diff --git a/Sources/NIOCore/AsyncSequences/NIOAsyncSequenceProducer.swift b/Sources/NIOCore/AsyncSequences/NIOAsyncSequenceProducer.swift index d8a41e434b..e6484d8464 100644 --- a/Sources/NIOCore/AsyncSequences/NIOAsyncSequenceProducer.swift +++ b/Sources/NIOCore/AsyncSequences/NIOAsyncSequenceProducer.swift @@ -290,7 +290,7 @@ extension NIOAsyncSequenceProducer { /// This can be called more than once and returns to the caller immediately /// without blocking for any awaiting consumption from the iteration. /// - /// - Parameter contentsOf: The sequence to yield. + /// - Parameter sequence: The sequence to yield. /// - Returns: A ``NIOAsyncSequenceProducer/Source/YieldResult`` that indicates if the yield was successful /// and if more elements should be produced. @inlinable diff --git a/Sources/NIOCore/AsyncSequences/NIOAsyncWriter.swift b/Sources/NIOCore/AsyncSequences/NIOAsyncWriter.swift index 64b74b1818..badc34f967 100644 --- a/Sources/NIOCore/AsyncSequences/NIOAsyncWriter.swift +++ b/Sources/NIOCore/AsyncSequences/NIOAsyncWriter.swift @@ -279,7 +279,7 @@ public struct NIOAsyncWriter< /// /// This can be called more than once and from multiple `Task`s at the same time. /// - /// - Parameter contentsOf: The sequence to yield. + /// - Parameter sequence: The sequence to yield. @inlinable public func yield(contentsOf sequence: S) async throws where S.Element == Element { try await self._storage.yield(contentsOf: sequence) diff --git a/Sources/NIOCore/AsyncSequences/NIOThrowingAsyncSequenceProducer.swift b/Sources/NIOCore/AsyncSequences/NIOThrowingAsyncSequenceProducer.swift index 7b95ee86f2..b807f6f407 100644 --- a/Sources/NIOCore/AsyncSequences/NIOThrowingAsyncSequenceProducer.swift +++ b/Sources/NIOCore/AsyncSequences/NIOThrowingAsyncSequenceProducer.swift @@ -335,7 +335,7 @@ extension NIOThrowingAsyncSequenceProducer { /// This can be called more than once and returns to the caller immediately /// without blocking for any awaiting consumption from the iteration. /// - /// - Parameter contentsOf: The sequence to yield. + /// - Parameter sequence: The sequence to yield. /// - Returns: A ``NIOThrowingAsyncSequenceProducer/Source/YieldResult`` that indicates if the yield was successful /// and if more elements should be produced. @inlinable diff --git a/Sources/NIOCore/ByteBuffer-aux.swift b/Sources/NIOCore/ByteBuffer-aux.swift index 94b643dd95..799b3f8511 100644 --- a/Sources/NIOCore/ByteBuffer-aux.swift +++ b/Sources/NIOCore/ByteBuffer-aux.swift @@ -25,10 +25,10 @@ extension ByteBuffer { /// Get `length` bytes starting at `index` and return the result as `[UInt8]`. This will not change the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index of the bytes of interest into the `ByteBuffer`. - /// - length: The number of bytes of interest. - /// - returns: A `[UInt8]` value containing the bytes of interest or `nil` if the bytes `ByteBuffer` are not readable. + /// - Parameters: + /// - index: The starting index of the bytes of interest into the `ByteBuffer`. + /// - length: The number of bytes of interest. + /// - Returns: A `[UInt8]` value containing the bytes of interest or `nil` if the bytes `ByteBuffer` are not readable. @inlinable public func getBytes(at index: Int, length: Int) -> [UInt8]? { guard let range = self.rangeWithinReadableBytes(index: index, length: length) else { @@ -46,9 +46,9 @@ extension ByteBuffer { /// Read `length` bytes off this `ByteBuffer`, move the reader index forward by `length` bytes and return the result /// as `[UInt8]`. /// - /// - parameters: - /// - length: The number of bytes to be read from this `ByteBuffer`. - /// - returns: A `[UInt8]` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. + /// - Parameters: + /// - length: The number of bytes to be read from this `ByteBuffer`. + /// - Returns: A `[UInt8]` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. @inlinable public mutating func readBytes(length: Int) -> [UInt8]? { guard let result = self.getBytes(at: self.readerIndex, length: length) else { @@ -62,9 +62,9 @@ extension ByteBuffer { /// Write the static `string` into this `ByteBuffer` using UTF-8 encoding, moving the writer index forward appropriately. /// - /// - parameters: - /// - string: The string to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeStaticString(_ string: StaticString) -> Int { @@ -75,10 +75,10 @@ extension ByteBuffer { /// Write the static `string` into this `ByteBuffer` at `index` using UTF-8 encoding, moving the writer index forward appropriately. /// - /// - parameters: - /// - string: The string to write. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written. @inlinable public mutating func setStaticString(_ string: StaticString, at index: Int) -> Int { // please do not replace the code below with code that uses `string.withUTF8Buffer { ... }` (see SR-7541) @@ -94,10 +94,10 @@ extension ByteBuffer { // MARK: Hex encoded string APIs /// Write ASCII hexadecimal `string` into this `ByteBuffer` as raw bytes, decoding the hexadecimal & moving the writer index forward appropriately. /// This method will throw if the string input is not of the "plain" hex encoded format. - /// - parameters: - /// - plainHexEncodedBytes: The hex encoded string to write. Plain hex dump format is hex bytes optionally separated by spaces, i.e. `48 65 6c 6c 6f` or `48656c6c6f` for `Hello`. + /// - Parameters: + /// - plainHexEncodedBytes: The hex encoded string to write. Plain hex dump format is hex bytes optionally separated by spaces, i.e. `48 65 6c 6c 6f` or `48656c6c6f` for `Hello`. /// This format is compatible with `xxd` CLI utility. - /// - returns: The number of bytes written. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writePlainHexEncodedBytes(_ plainHexEncodedBytes: String) throws -> Int { @@ -118,9 +118,9 @@ extension ByteBuffer { // MARK: String APIs /// Write `string` into this `ByteBuffer` using UTF-8 encoding, moving the writer index forward appropriately. /// - /// - parameters: - /// - string: The string to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeString(_ string: String) -> Int { @@ -131,9 +131,9 @@ extension ByteBuffer { /// Write `string` into this `ByteBuffer` null terminated using UTF-8 encoding, moving the writer index forward appropriately. /// - /// - parameters: - /// - string: The string to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeNullTerminatedString(_ string: String) -> Int { @@ -157,10 +157,10 @@ extension ByteBuffer { /// Write `string` into this `ByteBuffer` at `index` using UTF-8 encoding. Does not move the writer index. /// - /// - parameters: - /// - string: The string to write. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func setString(_ string: String, at index: Int) -> Int { @@ -179,10 +179,10 @@ extension ByteBuffer { /// Write `string` null terminated into this `ByteBuffer` at `index` using UTF-8 encoding. Does not move the writer index. /// - /// - parameters: - /// - string: The string to write. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written. @inlinable public mutating func setNullTerminatedString(_ string: String, at index: Int) -> Int { let length = self.setString(string, at: index) @@ -193,10 +193,10 @@ extension ByteBuffer { /// Get the string at `index` from this `ByteBuffer` decoding using the UTF-8 encoding. Does not move the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index into `ByteBuffer` containing the string of interest. - /// - length: The number of bytes making up the string. - /// - returns: A `String` value containing the UTF-8 decoded selected bytes from this `ByteBuffer` or `nil` if + /// - Parameters: + /// - index: The starting index into `ByteBuffer` containing the string of interest. + /// - length: The number of bytes making up the string. + /// - Returns: A `String` value containing the UTF-8 decoded selected bytes from this `ByteBuffer` or `nil` if /// the requested bytes are not readable. @inlinable public func getString(at index: Int, length: Int) -> String? { @@ -212,9 +212,9 @@ extension ByteBuffer { /// Get the string at `index` from this `ByteBuffer` decoding using the UTF-8 encoding. Does not move the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index into `ByteBuffer` containing the null terminated string of interest. - /// - returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there isn't a complete null-terminated string, + /// - Parameters: + /// - index: The starting index into `ByteBuffer` containing the null terminated string of interest. + /// - Returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there isn't a complete null-terminated string, /// including null-terminator, in the readable bytes after `index` in the buffer @inlinable public func getNullTerminatedString(at index: Int) -> String? { @@ -237,9 +237,9 @@ extension ByteBuffer { /// Read `length` bytes off this `ByteBuffer`, decoding it as `String` using the UTF-8 encoding. Move the reader index forward by `length`. /// - /// - parameters: - /// - length: The number of bytes making up the string. - /// - returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there aren't at least `length` bytes readable. + /// - Parameters: + /// - length: The number of bytes making up the string. + /// - Returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there aren't at least `length` bytes readable. @inlinable public mutating func readString(length: Int) -> String? { guard let result = self.getString(at: self.readerIndex, length: length) else { @@ -252,7 +252,7 @@ extension ByteBuffer { /// Read a null terminated string off this `ByteBuffer`, decoding it as `String` using the UTF-8 encoding. Move the reader index /// forward by the string's length and its null terminator. /// - /// - returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there isn't a complete null-terminated string, + /// - Returns: A `String` value deserialized from this `ByteBuffer` or `nil` if there isn't a complete null-terminated string, /// including null-terminator, in the readable bytes of the buffer @inlinable public mutating func readNullTerminatedString() -> String? { @@ -267,9 +267,9 @@ extension ByteBuffer { // MARK: Substring APIs /// Write `substring` into this `ByteBuffer` using UTF-8 encoding, moving the writer index forward appropriately. /// - /// - parameters: - /// - substring: The substring to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - substring: The substring to write. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeSubstring(_ substring: Substring) -> Int { @@ -280,10 +280,10 @@ extension ByteBuffer { /// Write `substring` into this `ByteBuffer` at `index` using UTF-8 encoding. Does not move the writer index. /// - /// - parameters: - /// - substring: The substring to write. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written + /// - Parameters: + /// - substring: The substring to write. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written @discardableResult @inlinable public mutating func setSubstring(_ substring: Substring, at index: Int) -> Int { @@ -304,9 +304,9 @@ extension ByteBuffer { // MARK: DispatchData APIs /// Write `dispatchData` into this `ByteBuffer`, moving the writer index forward appropriately. /// - /// - parameters: - /// - dispatchData: The `DispatchData` instance to write to the `ByteBuffer`. - /// - returns: The number of bytes written. + /// - Parameters: + /// - dispatchData: The `DispatchData` instance to write to the `ByteBuffer`. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeDispatchData(_ dispatchData: DispatchData) -> Int { @@ -317,10 +317,10 @@ extension ByteBuffer { /// Write `dispatchData` into this `ByteBuffer` at `index`. Does not move the writer index. /// - /// - parameters: - /// - dispatchData: The `DispatchData` to write. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - dispatchData: The `DispatchData` to write. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func setDispatchData(_ dispatchData: DispatchData, at index: Int) -> Int { @@ -337,10 +337,10 @@ extension ByteBuffer { /// Get the bytes at `index` from this `ByteBuffer` as a `DispatchData`. Does not move the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index into `ByteBuffer` containing the string of interest. - /// - length: The number of bytes. - /// - returns: A `DispatchData` value deserialized from this `ByteBuffer` or `nil` if the requested bytes + /// - Parameters: + /// - index: The starting index into `ByteBuffer` containing the string of interest. + /// - length: The number of bytes. + /// - Returns: A `DispatchData` value deserialized from this `ByteBuffer` or `nil` if the requested bytes /// are not readable. @inlinable public func getDispatchData(at index: Int, length: Int) -> DispatchData? { @@ -354,9 +354,9 @@ extension ByteBuffer { /// Read `length` bytes off this `ByteBuffer` and return them as a `DispatchData`. Move the reader index forward by `length`. /// - /// - parameters: - /// - length: The number of bytes. - /// - returns: A `DispatchData` value containing the bytes from this `ByteBuffer` or `nil` if there aren't at least `length` bytes readable. + /// - Parameters: + /// - length: The number of bytes. + /// - Returns: A `DispatchData` value containing the bytes from this `ByteBuffer` or `nil` if there aren't at least `length` bytes readable. @inlinable public mutating func readDispatchData(length: Int) -> DispatchData? { guard let result = self.getDispatchData(at: self.readerIndex, length: length) else { @@ -374,9 +374,9 @@ extension ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed. - /// - returns: The number of bytes read. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed. + /// - Returns: The number of bytes read. @discardableResult @inlinable public mutating func readWithUnsafeReadableBytes(_ body: (UnsafeRawBufferPointer) throws -> Int) rethrows -> Int { @@ -390,9 +390,9 @@ extension ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed. - /// - returns: The number of bytes read. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed. + /// - Returns: The number of bytes read. @discardableResult @inlinable public mutating func readWithUnsafeMutableReadableBytes( @@ -405,10 +405,10 @@ extension ByteBuffer { /// Copy `buffer`'s readable bytes into this `ByteBuffer` starting at `index`. Does not move any of the reader or writer indices. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to copy. - /// - index: The index for the first byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - buffer: The `ByteBuffer` to copy. + /// - index: The index for the first byte. + /// - Returns: The number of bytes written. @discardableResult @available(*, deprecated, renamed: "setBuffer(_:at:)") public mutating func set(buffer: ByteBuffer, at index: Int) -> Int { @@ -417,10 +417,10 @@ extension ByteBuffer { /// Copy `buffer`'s readable bytes into this `ByteBuffer` starting at `index`. Does not move any of the reader or writer indices. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to copy. - /// - index: The index for the first byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - buffer: The `ByteBuffer` to copy. + /// - index: The index for the first byte. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func setBuffer(_ buffer: ByteBuffer, at index: Int) -> Int { @@ -432,9 +432,9 @@ extension ByteBuffer { /// Write `buffer`'s readable bytes into this `ByteBuffer` starting at `writerIndex`. This will move both this /// `ByteBuffer`'s writer index as well as `buffer`'s reader index by the number of bytes readable in `buffer`. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to write. - /// - returns: The number of bytes written to this `ByteBuffer` which is equal to the number of bytes read from `buffer`. + /// - Parameters: + /// - buffer: The `ByteBuffer` to write. + /// - Returns: The number of bytes written to this `ByteBuffer` which is equal to the number of bytes read from `buffer`. @discardableResult @inlinable public mutating func writeBuffer(_ buffer: inout ByteBuffer) -> Int { @@ -446,9 +446,9 @@ extension ByteBuffer { /// Write `bytes`, a `Sequence` of `UInt8` into this `ByteBuffer`. Moves the writer index forward by the number of bytes written. /// - /// - parameters: - /// - bytes: A `Collection` of `UInt8` to be written. - /// - returns: The number of bytes written or `bytes.count`. + /// - Parameters: + /// - bytes: A `Collection` of `UInt8` to be written. + /// - Returns: The number of bytes written or `bytes.count`. @discardableResult @inlinable public mutating func writeBytes(_ bytes: Bytes) -> Int where Bytes.Element == UInt8 { @@ -459,9 +459,9 @@ extension ByteBuffer { /// Write `bytes` into this `ByteBuffer`. Moves the writer index forward by the number of bytes written. /// - /// - parameters: - /// - bytes: An `UnsafeRawBufferPointer` - /// - returns: The number of bytes written or `bytes.count`. + /// - Parameters: + /// - bytes: An `UnsafeRawBufferPointer` + /// - Returns: The number of bytes written or `bytes.count`. @discardableResult @inlinable public mutating func writeBytes(_ bytes: UnsafeRawBufferPointer) -> Int { @@ -472,9 +472,10 @@ extension ByteBuffer { /// Writes `byte` `count` times. Moves the writer index forward by the number of bytes written. /// - /// - parameter byte: The `UInt8` byte to repeat. - /// - parameter count: How many times to repeat the given `byte` - /// - returns: How many bytes were written. + /// - Parameters: + /// - byte: The `UInt8` byte to repeat. + /// - count: How many times to repeat the given `byte` + /// - Returns: How many bytes were written. @discardableResult @inlinable public mutating func writeRepeatingByte(_ byte: UInt8, count: Int) -> Int { @@ -485,9 +486,11 @@ extension ByteBuffer { /// Sets the given `byte` `count` times at the given `index`. Will reserve more memory if necessary. Does not move the writer index. /// - /// - parameter byte: The `UInt8` byte to repeat. - /// - parameter count: How many times to repeat the given `byte` - /// - returns: How many bytes were written. + /// - Parameters: + /// - byte: The `UInt8` byte to repeat. + /// - count: How many times to repeat the given `byte` + /// - index: The starting index of the bytes into the `ByteBuffer`. + /// - Returns: How many bytes were written. @discardableResult @inlinable public mutating func setRepeatingByte(_ byte: UInt8, count: Int, at index: Int) -> Int { @@ -504,9 +507,9 @@ extension ByteBuffer { /// `ByteBuffer` sharing the underlying storage with the `ByteBuffer` the method was invoked on. The returned /// `ByteBuffer` will contain the bytes in the range `readerIndex.. ByteBuffer { // must work, bytes definitely in the buffer// must work, bytes definitely in the buffer @@ -520,11 +523,11 @@ extension ByteBuffer { /// original `ByteBuffer`. /// The `readerIndex` of the returned `ByteBuffer` will be `0`, the `writerIndex` will be `length`. /// - /// - note: Because `ByteBuffer` implements copy-on-write a copy of the storage will be automatically triggered when either of the `ByteBuffer`s sharing storage is written to. + /// - Note: Because `ByteBuffer` implements copy-on-write a copy of the storage will be automatically triggered when either of the `ByteBuffer`s sharing storage is written to. /// - /// - parameters: - /// - length: The number of bytes to slice off. - /// - returns: A `ByteBuffer` sharing storage containing `length` bytes or `nil` if the not enough bytes were readable. + /// - Parameters: + /// - length: The number of bytes to slice off. + /// - Returns: A `ByteBuffer` sharing storage containing `length` bytes or `nil` if the not enough bytes were readable. @inlinable public mutating func readSlice(length: Int) -> ByteBuffer? { guard let result = self.getSlice_inlineAlways(at: self.readerIndex, length: length) else { @@ -549,9 +552,9 @@ extension ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value. - /// - returns: The value `body` returned in the second tuple component. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value. + /// - Returns: The value `body` returned in the second tuple component. @inlinable public mutating func readWithUnsafeMutableReadableBytes( _ body: (UnsafeMutableRawBufferPointer) throws -> (Int, T) @@ -566,9 +569,9 @@ extension ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value. - /// - returns: The value `body` returned in the second tuple component. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and returns the number of bytes it processed along with some other value. + /// - Returns: The value `body` returned in the second tuple component. @inlinable public mutating func readWithUnsafeReadableBytes( _ body: (UnsafeRawBufferPointer) throws -> (Int, T) @@ -689,7 +692,7 @@ extension ByteBuffer { /// This may allocate a new `ByteBuffer` with enough space to fit `buffer` and potentially some extra space using /// the default allocator. /// - /// - note: Use this method only if you deliberately want to reallocate a potentially smaller `ByteBuffer` than the + /// - Note: Use this method only if you deliberately want to reallocate a potentially smaller `ByteBuffer` than the /// one you already have. Given that `ByteBuffer` is a value type, defensive copies are not necessary. If /// you have a `ByteBuffer` but would like the `readerIndex` to start at `0`, consider `readSlice` instead. /// @@ -743,7 +746,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `string` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(string: String) -> ByteBuffer { var buffer = self.buffer(capacity: string.utf8.count) @@ -755,7 +758,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `string` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(substring string: Substring) -> ByteBuffer { var buffer = self.buffer(capacity: string.utf8.count) @@ -767,7 +770,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `string` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(staticString string: StaticString) -> ByteBuffer { var buffer = self.buffer(capacity: string.utf8CodeUnitCount) @@ -779,7 +782,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `bytes` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(bytes: Bytes) -> ByteBuffer where Bytes.Element == UInt8 { var buffer = self.buffer(capacity: bytes.underestimatedCount) @@ -791,7 +794,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `bytes` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(plainHexEncodedBytes string: String) throws -> ByteBuffer { var buffer = self.buffer(capacity: string.utf8.count / 2) @@ -804,7 +807,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with enough space to fit `integer` and potentially some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer( integer: I, @@ -820,7 +823,7 @@ extension ByteBufferAllocator { /// /// This will allocate a new `ByteBuffer` with at least `count` bytes. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(repeating byte: UInt8, count: Int) -> ByteBuffer { var buffer = self.buffer(capacity: count) @@ -832,11 +835,11 @@ extension ByteBufferAllocator { /// /// This may allocate a new `ByteBuffer` with enough space to fit `buffer` and potentially some extra space. /// - /// - note: Use this method only if you deliberately want to reallocate a potentially smaller `ByteBuffer` than the + /// - Note: Use this method only if you deliberately want to reallocate a potentially smaller `ByteBuffer` than the /// one you already have. Given that `ByteBuffer` is a value type, defensive copies are not necessary. If /// you have a `ByteBuffer` but would like the `readerIndex` to start at `0`, consider `readSlice` instead. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(buffer: ByteBuffer) -> ByteBuffer { var newBuffer = self.buffer(capacity: buffer.readableBytes) @@ -850,7 +853,7 @@ extension ByteBufferAllocator { /// This will allocate a new `ByteBuffer` with enough space to fit the bytes of the `DispatchData` and potentially /// some extra space. /// - /// - returns: The `ByteBuffer` containing the written bytes. + /// - Returns: The `ByteBuffer` containing the written bytes. @inlinable public func buffer(dispatchData: DispatchData) -> ByteBuffer { var buffer = self.buffer(capacity: dispatchData.count) @@ -866,9 +869,9 @@ extension Optional where Wrapped == ByteBuffer { /// /// This method will not modify `buffer`, meaning its `readerIndex` and `writerIndex` stays intact. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to write. - /// - returns: The number of bytes written to this `ByteBuffer` which is equal to the number of `readableBytes` in + /// - Parameters: + /// - buffer: The `ByteBuffer` to write. + /// - Returns: The number of bytes written to this `ByteBuffer` which is equal to the number of `readableBytes` in /// `buffer`. @discardableResult @inlinable @@ -883,9 +886,9 @@ extension Optional where Wrapped == ByteBuffer { /// This will move both this `ByteBuffer`'s writer index as well as `buffer`'s reader index by the number of bytes /// readable in `buffer`. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to write. - /// - returns: The number of bytes written to this `ByteBuffer` which is equal to the number of bytes read from `buffer`. + /// - Parameters: + /// - buffer: The `ByteBuffer` to write. + /// - Returns: The number of bytes written to this `ByteBuffer` which is equal to the number of bytes read from `buffer`. @discardableResult @inlinable public mutating func setOrWriteBuffer(_ buffer: inout ByteBuffer) -> Int { diff --git a/Sources/NIOCore/ByteBuffer-binaryEncodedLengthPrefix.swift b/Sources/NIOCore/ByteBuffer-binaryEncodedLengthPrefix.swift index 88bc56d7ce..cf97570d0f 100644 --- a/Sources/NIOCore/ByteBuffer-binaryEncodedLengthPrefix.swift +++ b/Sources/NIOCore/ByteBuffer-binaryEncodedLengthPrefix.swift @@ -111,8 +111,8 @@ extension ByteBuffer { /// Therefore, this function is most performant if the strategy is able to use the same number of bytes that it reserved. /// /// - Parameters: - /// - strategy: The strategy to use for encoding the length. - /// - writeData: A closure that takes a buffer, writes some data to it, and returns the number of bytes written. + /// - strategy: The strategy to use for encoding the length. + /// - writeData: A closure that takes a buffer, writes some data to it, and returns the number of bytes written. /// - Returns: Number of total bytes written. This is the length of the written data + the number of bytes used to write the length before it. @discardableResult @inlinable diff --git a/Sources/NIOCore/ByteBuffer-conversions.swift b/Sources/NIOCore/ByteBuffer-conversions.swift index bfcb9f6dd9..ca4bdf1fc4 100644 --- a/Sources/NIOCore/ByteBuffer-conversions.swift +++ b/Sources/NIOCore/ByteBuffer-conversions.swift @@ -19,7 +19,7 @@ import Dispatch extension Array where Element == UInt8 { /// Creates a `[UInt8]` from the given buffer. The entire readable portion of the buffer will be read. - /// - parameter buffer: The buffer to read. + /// - Parameter buffer: The buffer to read. @inlinable public init(buffer: ByteBuffer) { var buffer = buffer @@ -31,7 +31,7 @@ extension Array where Element == UInt8 { extension String { /// Creates a `String` from a given `ByteBuffer`. The entire readable portion of the buffer will be read. - /// - parameter buffer: The buffer to read. + /// - Parameter buffer: The buffer to read. @inlinable public init(buffer: ByteBuffer) { var buffer = buffer @@ -40,9 +40,9 @@ extension String { /// Creates a `String` from a given `Int` with a given base (`radix`), padded with zeroes to the provided `padding` size. /// - /// - parameters: - /// - radix: radix base to use for conversion. - /// - padding: the desired length of the resulting string. + /// - Parameters: + /// - radix: radix base to use for conversion. + /// - padding: the desired length of the resulting string. @inlinable internal init(_ value: Value, radix: Int, padding: Int) where Value: BinaryInteger { let formatted = String(value, radix: radix) @@ -54,7 +54,7 @@ extension String { extension DispatchData { /// Creates a `DispatchData` from a given `ByteBuffer`. The entire readable portion of the buffer will be read. - /// - parameter buffer: The buffer to read. + /// - Parameter buffer: The buffer to read. @inlinable public init(buffer: ByteBuffer) { var buffer = buffer diff --git a/Sources/NIOCore/ByteBuffer-core.swift b/Sources/NIOCore/ByteBuffer-core.swift index d501d0205a..f85928451e 100644 --- a/Sources/NIOCore/ByteBuffer-core.swift +++ b/Sources/NIOCore/ByteBuffer-core.swift @@ -80,7 +80,7 @@ extension _ByteBufferSlice: CustomStringConvertible { /// The preferred allocator for `ByteBuffer` values. The allocation strategy is opaque but is currently libc's /// `malloc`, `realloc` and `free`. /// -/// - note: `ByteBufferAllocator` is thread-safe. +/// - Note: `ByteBufferAllocator` is thread-safe. public struct ByteBufferAllocator: Sendable { /// Create a fresh `ByteBufferAllocator`. In the future the allocator might use for example allocation pools and @@ -110,13 +110,13 @@ public struct ByteBufferAllocator: Sendable { /// Request a freshly allocated `ByteBuffer` of size `capacity` or larger. /// - /// - note: The passed `capacity` is the `ByteBuffer`'s initial capacity, it will grow automatically if necessary. + /// - Note: The passed `capacity` is the `ByteBuffer`'s initial capacity, it will grow automatically if necessary. /// - /// - note: If `capacity` is `0`, this function will not allocate. If you want to trigger an allocation immediately, + /// - Note: If `capacity` is `0`, this function will not allocate. If you want to trigger an allocation immediately, /// also call `.clear()`. /// - /// - parameters: - /// - capacity: The initial capacity of the returned `ByteBuffer`. + /// - Parameters: + /// - capacity: The initial capacity of the returned `ByteBuffer`. @inlinable public func buffer(capacity: Int) -> ByteBuffer { precondition(capacity >= 0, "ByteBuffer capacity must be positive.") @@ -597,8 +597,8 @@ public struct ByteBuffer { /// If the buffer already has space to store the requested number of bytes, this method will be /// a no-op. /// - /// - parameters: - /// - minimumCapacity: The minimum number of bytes this buffer must be able to store. + /// - Parameters: + /// - minimumCapacity: The minimum number of bytes this buffer must be able to store. @inlinable public mutating func reserveCapacity(_ minimumCapacity: Int) { guard minimumCapacity > self.capacity else { @@ -649,9 +649,9 @@ public struct ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes. - /// - returns: The value returned by `body`. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes. + /// - Returns: The value returned by `body`. @inlinable public mutating func withUnsafeMutableReadableBytes( _ body: (UnsafeMutableRawBufferPointer) throws -> T @@ -665,13 +665,13 @@ public struct ByteBuffer { /// Yields the bytes currently writable (`bytesWritable` = `capacity` - `writerIndex`). Before reading those bytes you must first /// write to them otherwise you will trigger undefined behaviour. The writer index will remain unchanged. /// - /// - note: In almost all cases you should use `writeWithUnsafeMutableBytes` which will move the write pointer instead of this method + /// - Note: In almost all cases you should use `writeWithUnsafeMutableBytes` which will move the write pointer instead of this method /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and return the number of bytes written. - /// - returns: The number of bytes written. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and return the number of bytes written. + /// - Returns: The number of bytes written. @inlinable public mutating func withUnsafeMutableWritableBytes( _ body: (UnsafeMutableRawBufferPointer) throws -> T @@ -684,10 +684,10 @@ public struct ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - minimumWritableBytes: The number of writable bytes to reserve capacity for before vending the `ByteBuffer` pointer to `body`. - /// - body: The closure that will accept the yielded bytes and return the number of bytes written. - /// - returns: The number of bytes written. + /// - Parameters: + /// - minimumWritableBytes: The number of writable bytes to reserve capacity for before vending the `ByteBuffer` pointer to `body`. + /// - body: The closure that will accept the yielded bytes and return the number of bytes written. + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeWithUnsafeMutableBytes( @@ -741,9 +741,9 @@ public struct ByteBuffer { /// /// - warning: Do not escape the pointer from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes. - /// - returns: The value returned by `body`. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes. + /// - Returns: The value returned by `body`. @inlinable public func withUnsafeReadableBytes(_ body: (UnsafeRawBufferPointer) throws -> T) rethrows -> T { // This is safe, writerIndex >= readerIndex @@ -759,9 +759,9 @@ public struct ByteBuffer { /// the bytes and you also must call `storageManagement.release()` if you no longer require those bytes. Calls to /// `retain` and `release` must be balanced. /// - /// - parameters: - /// - body: The closure that will accept the yielded bytes and the `storageManagement`. - /// - returns: The value returned by `body`. + /// - Parameters: + /// - body: The closure that will accept the yielded bytes and the `storageManagement`. + /// - Returns: The value returned by `body`. @inlinable public func withUnsafeReadableBytesWithStorageManagement( _ body: (UnsafeRawBufferPointer, Unmanaged) throws -> T @@ -798,10 +798,10 @@ public struct ByteBuffer { /// /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The index the requested slice starts at. - /// - length: The length of the requested slice. - /// - returns: A `ByteBuffer` containing the selected bytes as readable bytes or `nil` if the selected bytes were + /// - Parameters: + /// - index: The index the requested slice starts at. + /// - length: The length of the requested slice. + /// - Returns: A `ByteBuffer` containing the selected bytes as readable bytes or `nil` if the selected bytes were /// not readable in the initial `ByteBuffer`. @inlinable public func getSlice(at index: Int, length: Int) -> ByteBuffer? { @@ -859,7 +859,7 @@ public struct ByteBuffer { /// Discard the bytes before the reader index. The byte at index `readerIndex` before calling this method will be /// at index `0` after the call returns. /// - /// - returns: `true` if one or more bytes have been discarded, `false` if there are no bytes to discard. + /// - Returns: `true` if one or more bytes have been discarded, `false` if there are no bytes to discard. @inlinable @discardableResult public mutating func discardReadBytes() -> Bool { guard self._readerIndex > 0 else { @@ -930,7 +930,7 @@ public struct ByteBuffer { /// of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a `ByteBuffer` /// for a new use-case. /// - /// - note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an + /// - Note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an /// allocation is necessary this will be cheaper as the copy of the storage is elided. @inlinable public mutating func clear() { @@ -946,11 +946,11 @@ public struct ByteBuffer { /// of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a `ByteBuffer` /// for a new use-case. /// - /// - note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an + /// - Note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an /// allocation is necessary this will be cheaper as the copy of the storage is elided. /// - /// - parameters: - /// - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer + /// - Parameters: + /// - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer @available(*, deprecated, message: "Use an `Int` as the argument") public mutating func clear(minimumCapacity: UInt32) { self.clear(minimumCapacity: Int(minimumCapacity)) @@ -960,11 +960,11 @@ public struct ByteBuffer { /// of a freshly allocated one, if possible without allocations. This is the cheapest way to recycle a `ByteBuffer` /// for a new use-case. /// - /// - note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an + /// - Note: This method will allocate if the underlying storage is referenced by another `ByteBuffer`. Even if an /// allocation is necessary this will be cheaper as the copy of the storage is elided. /// - /// - parameters: - /// - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer + /// - Parameters: + /// - minimumCapacity: The minimum capacity that will be (re)allocated for this buffer @inlinable public mutating func clear(minimumCapacity: Int) { precondition(minimumCapacity >= 0, "Cannot have a minimum capacity < 0") @@ -993,7 +993,7 @@ extension ByteBuffer: CustomStringConvertible, CustomDebugStringConvertible { /// Buffers larger that 64 bytes will get truncated when printing out. /// The format of the description is not API. /// - /// - returns: A description of this `ByteBuffer`. + /// - Returns: A description of this `ByteBuffer`. public var description: String { "[\(self.hexDump(format: .compact(maxBytes: 64)))](\(self.readableBytes) bytes)" } @@ -1024,7 +1024,7 @@ extension ByteBuffer { /// - warning: By contract the bytes between (including) `readerIndex` and (excluding) `writerIndex` must be /// initialised, ie. have been written before. Also the `readerIndex` must always be less than or equal /// to the `writerIndex`. Failing to meet either of these requirements leads to undefined behaviour. - /// - parameters: + /// - Parameters: /// - offset: The number of bytes to move the reader index forward by. @inlinable public mutating func moveReaderIndex(forwardBy offset: Int) { @@ -1041,7 +1041,7 @@ extension ByteBuffer { /// - warning: By contract the bytes between (including) `readerIndex` and (excluding) `writerIndex` must be /// initialised, ie. have been written before. Also the `readerIndex` must always be less than or equal /// to the `writerIndex`. Failing to meet either of these requirements leads to undefined behaviour. - /// - parameters: + /// - Parameters: /// - offset: The offset in bytes to set the reader index to. @inlinable public mutating func moveReaderIndex(to offset: Int) { @@ -1058,7 +1058,7 @@ extension ByteBuffer { /// - warning: By contract the bytes between (including) `readerIndex` and (excluding) `writerIndex` must be /// initialised, ie. have been written before. Also the `readerIndex` must always be less than or equal /// to the `writerIndex`. Failing to meet either of these requirements leads to undefined behaviour. - /// - parameters: + /// - Parameters: /// - offset: The number of bytes to move the writer index forward by. @inlinable public mutating func moveWriterIndex(forwardBy offset: Int) { @@ -1075,7 +1075,7 @@ extension ByteBuffer { /// - warning: By contract the bytes between (including) `readerIndex` and (excluding) `writerIndex` must be /// initialised, ie. have been written before. Also the `readerIndex` must always be less than or equal /// to the `writerIndex`. Failing to meet either of these requirements leads to undefined behaviour. - /// - parameters: + /// - Parameters: /// - offset: The offset in bytes to set the reader index to. @inlinable public mutating func moveWriterIndex(to offset: Int) { @@ -1199,9 +1199,9 @@ extension ByteBuffer { /// This function will execute the provided block only if it is guaranteed to be able to avoid a copy-on-write /// operation. If it cannot execute the block the returned value will be `nil`. /// - /// - parameters: - /// - body: The modification operation to execute, with this `ByteBuffer` passed `inout` as an argument. - /// - returns: The return value of `body`. + /// - Parameters: + /// - body: The modification operation to execute, with this `ByteBuffer` passed `inout` as an argument. + /// - Returns: The return value of `body`. @inlinable public mutating func modifyIfUniquelyOwned(_ body: (inout ByteBuffer) throws -> T) rethrows -> T? { if isKnownUniquelyReferenced(&self._storage) { diff --git a/Sources/NIOCore/ByteBuffer-hex.swift b/Sources/NIOCore/ByteBuffer-hex.swift index 98efd89fa4..57801f3db2 100644 --- a/Sources/NIOCore/ByteBuffer-hex.swift +++ b/Sources/NIOCore/ByteBuffer-hex.swift @@ -71,8 +71,8 @@ extension ByteBuffer { /// Shared logic for `hexDumpPlain` and `hexDumpCompact`. /// Returns a `String` of hexadecimals digits of the readable bytes in the buffer. - /// - parameter - /// - separateWithWhitespace: Controls whether the hex deump will be separated by whitespaces. + /// - Parameter + /// - separateWithWhitespace: Controls whether the hex deump will be separated by whitespaces. private func _hexDump(separateWithWhitespace: Bool) -> String { var hexString = "" var capacity: Int @@ -101,9 +101,9 @@ extension ByteBuffer { /// Shared logic for `hexDumpPlain(maxBytes: Int)` and `hexDumpCompact(maxBytes: Int)`. /// - /// - parameters: - /// - maxBytes: The maximum amount of bytes presented in the dump. - /// - separateWithWhitespace: Controls whether the dump will be separated by whitespaces. + /// - Parameters: + /// - maxBytes: The maximum amount of bytes presented in the dump. + /// - separateWithWhitespace: Controls whether the dump will be separated by whitespaces. private func _hexDump(maxBytes: Int, separateWithWhitespace: Bool) -> String { // If the buffer length fits in the max bytes limit in the hex dump, just dump the whole thing. if self.readableBytes <= maxBytes { @@ -143,8 +143,8 @@ extension ByteBuffer { /// If the dump contains more than the `maxBytes` bytes, this function will return the first `maxBytes/2` /// and the last `maxBytes/2` of that, replacing the rest with `...`, i.e. `01 02 03 ... 09 11 12`. /// - /// - parameters: - /// - maxBytes: The maximum amount of bytes presented in the dump. + /// - Parameters: + /// - maxBytes: The maximum amount of bytes presented in the dump. private func hexDumpPlain(maxBytes: Int) -> String { self._hexDump(maxBytes: maxBytes, separateWithWhitespace: true) } @@ -163,18 +163,18 @@ extension ByteBuffer { /// If the dump contains more than the `maxBytes` bytes, this function will return the first `maxBytes/2` /// and the last `maxBytes/2` of that, replacing the rest with `...`, i.e. `010203...091112`. /// - /// - parameters: - /// - maxBytes: The maximum amount of bytes presented in the dump. + /// - Parameters: + /// - maxBytes: The maximum amount of bytes presented in the dump. private func hexDumpCompact(maxBytes: Int) -> String { self._hexDump(maxBytes: maxBytes, separateWithWhitespace: false) } /// Returns a `String` containing a detailed hex dump of this buffer. /// Intended to be used internally in ``hexDump(format:)`` - /// - parameters: - /// - lineOffset: an offset from the beginning of the outer buffer that is being dumped. It's used to print the line offset in hexdump -C format. - /// - paddingBefore: the amount of space to pad before the first byte dumped on this line, used in center and right columns. - /// - paddingAfter: the amount of sapce to pad after the last byte on this line, used in center and right columns. + /// - Parameters: + /// - lineOffset: an offset from the beginning of the outer buffer that is being dumped. It's used to print the line offset in hexdump -C format. + /// - paddingBefore: the amount of space to pad before the first byte dumped on this line, used in center and right columns. + /// - paddingAfter: the amount of sapce to pad after the last byte on this line, used in center and right columns. private func _hexDumpLine(lineOffset: Int, paddingBefore: Int = 0, paddingAfter: Int = 0) -> String { // Each line takes 78 visible characters + \n var result = "" @@ -255,8 +255,8 @@ extension ByteBuffer { /// with formatting sort of compatible with `hexdump -C`, but clipped on length. /// Dumps limit/2 first and limit/2 last bytes, with a separator line in between. /// - /// - parameters: - /// - maxBytes: Max bytes to dump. + /// - Parameters: + /// - maxBytes: Max bytes to dump. private func hexDumpDetailed(maxBytes: Int) -> String { if self.readableBytes <= maxBytes { return self.hexdumpDetailed() @@ -320,16 +320,16 @@ extension ByteBuffer { /// Returns a hex dump of this `ByteBuffer` in a preferred `HexDumpFormat`. /// - /// `hexDump` provides four formats: - /// - `.plain` — plain hex dump format with hex bytes separated by spaces, i.e. `48 65 6c 6c 6f` for `Hello`. This format is compatible with `xxd -r`. - /// - `.plain(maxBytes: Int)` — like `.plain`, but clipped to maximum bytes dumped. - /// - `.compact` — plain hexd dump without whitespaces. - /// - `.compact(maxBytes: Int)` — like `.compact`, but clipped to maximum bytes dumped. - /// - `.detailed` — detailed hex dump format with both hex, and ASCII representation of the bytes. This format is compatible with what `hexdump -C` outputs. - /// - `.detailed(maxBytes: Int)` — like `.detailed`, but clipped to maximum bytes dumped. + /// `hexDump` provides several formats: + /// - `.plain` — plain hex dump format with hex bytes separated by spaces, i.e. `48 65 6c 6c 6f` for `Hello`. This format is compatible with `xxd -r`. + /// - `.plain(maxBytes: Int)` — like `.plain`, but clipped to maximum bytes dumped. + /// - `.compact` — plain hexd dump without whitespaces. + /// - `.compact(maxBytes: Int)` — like `.compact`, but clipped to maximum bytes dumped. + /// - `.detailed` — detailed hex dump format with both hex, and ASCII representation of the bytes. This format is compatible with what `hexdump -C` outputs. + /// - `.detailed(maxBytes: Int)` — like `.detailed`, but clipped to maximum bytes dumped. /// - /// - parameters: - /// - format: ``HexDumpFormat`` to use for the dump. + /// - Parameters: + /// - format: ``HexDumpFormat`` to use for the dump. public func hexDump(format: HexDumpFormat) -> String { switch format.value { case .plain(let maxBytes): diff --git a/Sources/NIOCore/ByteBuffer-int.swift b/Sources/NIOCore/ByteBuffer-int.swift index cc5d23de46..d0fb026901 100644 --- a/Sources/NIOCore/ByteBuffer-int.swift +++ b/Sources/NIOCore/ByteBuffer-int.swift @@ -25,10 +25,10 @@ extension ByteBuffer { /// Read an integer off this `ByteBuffer`, move the reader index forward by the integer's byte size and return the result. /// - /// - parameters: - /// - endianness: The endianness of the integer in this `ByteBuffer` (defaults to big endian). - /// - as: the desired `FixedWidthInteger` type (optional parameter) - /// - returns: An integer value deserialized from this `ByteBuffer` or `nil` if there aren't enough bytes readable. + /// - Parameters: + /// - endianness: The endianness of the integer in this `ByteBuffer` (defaults to big endian). + /// - as: the desired `FixedWidthInteger` type (optional parameter) + /// - Returns: An integer value deserialized from this `ByteBuffer` or `nil` if there aren't enough bytes readable. @inlinable public mutating func readInteger(endianness: Endianness = .big, as: T.Type = T.self) -> T? { guard let result = self.getInteger(at: self.readerIndex, endianness: endianness, as: T.self) else { @@ -41,11 +41,11 @@ extension ByteBuffer { /// Get the integer at `index` from this `ByteBuffer`. Does not move the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index of the bytes for the integer into the `ByteBuffer`. - /// - endianness: The endianness of the integer in this `ByteBuffer` (defaults to big endian). - /// - as: the desired `FixedWidthInteger` type (optional parameter) - /// - returns: An integer value deserialized from this `ByteBuffer` or `nil` if the bytes of interest are not + /// - Parameters: + /// - index: The starting index of the bytes for the integer into the `ByteBuffer`. + /// - endianness: The endianness of the integer in this `ByteBuffer` (defaults to big endian). + /// - as: the desired `FixedWidthInteger` type (optional parameter) + /// - Returns: An integer value deserialized from this `ByteBuffer` or `nil` if the bytes of interest are not /// readable. @inlinable public func getInteger( @@ -75,11 +75,11 @@ extension ByteBuffer { /// Write `integer` into this `ByteBuffer`, moving the writer index forward appropriately. /// - /// - parameters: - /// - integer: The integer to serialize. - /// - endianness: The endianness to use, defaults to big endian. - /// - as: the desired `FixedWidthInteger` type (optional parameter) - /// - returns: The number of bytes written. + /// - Parameters: + /// - integer: The integer to serialize. + /// - endianness: The endianness to use, defaults to big endian. + /// - as: the desired `FixedWidthInteger` type (optional parameter) + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func writeInteger( @@ -94,12 +94,12 @@ extension ByteBuffer { /// Write `integer` into this `ByteBuffer` starting at `index`. This does not alter the writer index. /// - /// - parameters: - /// - integer: The integer to serialize. - /// - index: The index of the first byte to write. - /// - endianness: The endianness to use, defaults to big endian. - /// - as: the desired `FixedWidthInteger` type (optional parameter) - /// - returns: The number of bytes written. + /// - Parameters: + /// - integer: The integer to serialize. + /// - index: The index of the first byte to write. + /// - endianness: The endianness to use, defaults to big endian. + /// - as: the desired `FixedWidthInteger` type (optional parameter) + /// - Returns: The number of bytes written. @discardableResult @inlinable public mutating func setInteger( diff --git a/Sources/NIOCore/ByteBuffer-lengthPrefix.swift b/Sources/NIOCore/ByteBuffer-lengthPrefix.swift index 2941e7c467..6158a2dcd4 100644 --- a/Sources/NIOCore/ByteBuffer-lengthPrefix.swift +++ b/Sources/NIOCore/ByteBuffer-lengthPrefix.swift @@ -32,9 +32,9 @@ extension ByteBuffer { extension ByteBuffer { /// Prefixes a message written by `writeMessage` with the number of bytes written as an `Integer`. /// - Parameters: - /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). - /// - integer: the desired `Integer` type used to write the length prefix - /// - writeMessage: A closure that takes a buffer, writes a message to it and returns the number of bytes written + /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). + /// - integer: the desired `Integer` type used to write the length prefix + /// - writeMessage: A closure that takes a buffer, writes a message to it and returns the number of bytes written /// - Throws: If the number of bytes written during `writeMessage` can not be exactly represented as the given `Integer` i.e. if the number of bytes written is greater than `Integer.max` /// - Returns: Number of total bytes written @discardableResult @@ -78,9 +78,9 @@ extension ByteBuffer { /// /// The `readerIndex` is **not** moved forward if the length prefix could not be read or `self` does not contain enough bytes. Otherwise `readerIndex` is moved forward even if `readMessage` throws or returns nil. /// - Parameters: - /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). - /// - integer: the desired `Integer` type used to read the length prefix - /// - readMessage: A closure that takes a `ByteBuffer` slice which contains the message after the length prefix + /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). + /// - integer: the desired `Integer` type used to read the length prefix + /// - readMessage: A closure that takes a `ByteBuffer` slice which contains the message after the length prefix /// - Throws: if `readMessage` returns nil /// - Returns: `nil` if the length prefix could not be read, /// the length prefix is negative or @@ -105,8 +105,8 @@ extension ByteBuffer { /// /// If nil is returned, `readerIndex` is **not** moved forward. /// - Parameters: - /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). - /// - integer: the desired `Integer` type used to read the length prefix + /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). + /// - integer: the desired `Integer` type used to read the length prefix /// - Returns: `nil` if the length prefix could not be read, /// the length prefix is negative or /// the buffer does not contain enough bytes to read a message of this length. @@ -127,8 +127,9 @@ extension ByteBuffer { /// Gets an `Integer` from `self` and gets a slice of that length from `self` and returns it. /// /// - Parameters: - /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). - /// - integer: the desired `Integer` type used to get the length prefix + /// - index: The starting index of the bytes for the slice into the `ByteBuffer`. + /// - endianness: The endianness of the length prefix `Integer` in this `ByteBuffer` (defaults to big endian). + /// - integer: the desired `Integer` type used to get the length prefix /// - Returns: `nil` if the length prefix could not be read, /// the length prefix is negative or /// the buffer does not contain enough bytes to read a message of this length. diff --git a/Sources/NIOCore/ByteBuffer-views.swift b/Sources/NIOCore/ByteBuffer-views.swift index 9c0c0ab488..8563a301b8 100644 --- a/Sources/NIOCore/ByteBuffer-views.swift +++ b/Sources/NIOCore/ByteBuffer-views.swift @@ -253,10 +253,10 @@ extension ByteBuffer { /// Returns a view into some portion of the readable bytes of a `ByteBuffer`. /// - /// - parameters: + /// - Parameters: /// - index: The index the view should start at /// - length: The length of the view (in bytes) - /// - returns: A view into a portion of a `ByteBuffer` or `nil` if the requested bytes were not readable. + /// - Returns: A view into a portion of a `ByteBuffer` or `nil` if the requested bytes were not readable. @inlinable public func viewBytes(at index: Int, length: Int) -> ByteBufferView? { guard length >= 0 && index >= self.readerIndex && index <= self.writerIndex - length else { @@ -268,7 +268,7 @@ extension ByteBuffer { /// Create a `ByteBuffer` from the given `ByteBufferView`s range. /// - /// - parameter view: The `ByteBufferView` which you want to get a `ByteBuffer` from. + /// - Parameter view: The `ByteBufferView` which you want to get a `ByteBuffer` from. @inlinable public init(_ view: ByteBufferView) { self = view._buffer.getSlice(at: view.startIndex, length: view.count)! diff --git a/Sources/NIOCore/Channel.swift b/Sources/NIOCore/Channel.swift index 910caf4511..8d0af1fec5 100644 --- a/Sources/NIOCore/Channel.swift +++ b/Sources/NIOCore/Channel.swift @@ -18,7 +18,7 @@ import NIOConcurrencyHelpers /// /// - warning: If you are not implementing a custom `Channel` type, you should never call any of these. /// -/// - note: All methods must be called from the `EventLoop` thread. +/// - Note: All methods must be called from the `EventLoop` thread. public protocol ChannelCore: AnyObject { /// Returns the local bound `SocketAddress`. func localAddress0() throws -> SocketAddress @@ -28,34 +28,34 @@ public protocol ChannelCore: AnyObject { /// Register with the `EventLoop` to receive I/O notifications. /// - /// - parameters: - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func register0(promise: EventLoopPromise?) /// Register channel as already connected or bound socket. - /// - parameters: - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func registerAlreadyConfigured0(promise: EventLoopPromise?) /// Bind to a `SocketAddress`. /// - /// - parameters: - /// - to: The `SocketAddress` to which we should bind the `Channel`. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - to: The `SocketAddress` to which we should bind the `Channel`. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func bind0(to: SocketAddress, promise: EventLoopPromise?) /// Connect to a `SocketAddress`. /// - /// - parameters: - /// - to: The `SocketAddress` to which we should connect the `Channel`. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - to: The `SocketAddress` to which we should connect the `Channel`. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func connect0(to: SocketAddress, promise: EventLoopPromise?) /// Write the given data to the outbound buffer. /// - /// - parameters: - /// - data: The data to write, wrapped in a `NIOAny`. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - data: The data to write, wrapped in a `NIOAny`. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func write0(_ data: NIOAny, promise: EventLoopPromise?) /// Try to flush out all previous written messages that are pending. @@ -66,36 +66,36 @@ public protocol ChannelCore: AnyObject { /// Close the `Channel`. /// - /// - parameters: - /// - error: The `Error` which will be used to fail any pending writes. - /// - mode: The `CloseMode` to apply. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - error: The `Error` which will be used to fail any pending writes. + /// - mode: The `CloseMode` to apply. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func close0(error: Error, mode: CloseMode, promise: EventLoopPromise?) /// Trigger an outbound event. /// - /// - parameters: - /// - event: The triggered event. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - event: The triggered event. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func triggerUserOutboundEvent0(_ event: Any, promise: EventLoopPromise?) /// Called when data was read from the `Channel` but it was not consumed by any `ChannelInboundHandler` in the `ChannelPipeline`. /// - /// - parameters: - /// - data: The data that was read, wrapped in a `NIOAny`. + /// - Parameters: + /// - data: The data that was read, wrapped in a `NIOAny`. func channelRead0(_ data: NIOAny) /// Called when an inbound error was encountered but was not consumed by any `ChannelInboundHandler` in the `ChannelPipeline`. /// - /// - parameters: - /// - error: The `Error` that was encountered. + /// - Parameters: + /// - error: The `Error` that was encountered. func errorCaught0(error: Error) } /// A `Channel` is easiest thought of as a network socket. But it can be anything that is capable of I/O operations such /// as read, write, connect, and bind. /// -/// - note: All operations on `Channel` are thread-safe. +/// - Note: All operations on `Channel` are thread-safe. /// /// In SwiftNIO, all I/O operations are asynchronous and hence all operations on `Channel` are asynchronous too. This means /// that all I/O operations will return immediately, usually before the work has been completed. The `EventLoopPromise`s @@ -289,10 +289,10 @@ extension ChannelCore { /// types are supported, consider using a tagged union to store the type information like /// NIO's own `IOData`, which will minimise the amount of runtime type checking. /// - /// - parameters: - /// - data: The `NIOAny` to unwrap. - /// - as: The type to extract from the `NIOAny`. - /// - returns: The content of the `NIOAny`. + /// - Parameters: + /// - data: The `NIOAny` to unwrap. + /// - as: The type to extract from the `NIOAny`. + /// - Returns: The content of the `NIOAny`. @inlinable public func unwrapData(_ data: NIOAny, as: T.Type = T.self) -> T { data.forceAs() @@ -309,10 +309,10 @@ extension ChannelCore { /// using `unwrapData` instead. This method exists for rare use-cases where tolerating type /// mismatches is acceptable. /// - /// - parameters: - /// - data: The `NIOAny` to unwrap. - /// - as: The type to extract from the `NIOAny`. - /// - returns: The content of the `NIOAny`, or `nil` if the type is incorrect. + /// - Parameters: + /// - data: The `NIOAny` to unwrap. + /// - as: The type to extract from the `NIOAny`. + /// - Returns: The content of the `NIOAny`, or `nil` if the type is incorrect. /// - warning: If you are implementing a `ChannelCore`, you should use `unwrapData` unless you /// are doing something _extremely_ unusual. @inlinable @@ -327,8 +327,8 @@ extension ChannelCore { /// This can be called from `close0` to tear down the `ChannelPipeline` when closure is /// complete. /// - /// - parameters: - /// - channel: The `Channel` whose `ChannelPipeline` will be closed. + /// - Parameters: + /// - channel: The `Channel` whose `ChannelPipeline` will be closed. @available(*, deprecated, renamed: "removeHandlers(pipeline:)") public func removeHandlers(channel: Channel) { self.removeHandlers(pipeline: channel.pipeline) @@ -341,8 +341,8 @@ extension ChannelCore { /// This can be called from `close0` to tear down the `ChannelPipeline` when closure is /// complete. /// - /// - parameters: - /// - pipeline: The `ChannelPipline` to be closed. + /// - Parameters: + /// - pipeline: The `ChannelPipline` to be closed. public func removeHandlers(pipeline: ChannelPipeline) { pipeline.removeHandlers() } diff --git a/Sources/NIOCore/ChannelHandler.swift b/Sources/NIOCore/ChannelHandler.swift index c48b06faff..4b9229f2af 100644 --- a/Sources/NIOCore/ChannelHandler.swift +++ b/Sources/NIOCore/ChannelHandler.swift @@ -20,14 +20,14 @@ public protocol ChannelHandler: AnyObject { /// Called when this `ChannelHandler` is added to the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func handlerAdded(context: ChannelHandlerContext) /// Called when this `ChannelHandler` is removed from the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func handlerRemoved(context: ChannelHandlerContext) } @@ -45,9 +45,9 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.register` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func register(context: ChannelHandlerContext, promise: EventLoopPromise?) /// Called to request that the `Channel` bind to a specific `SocketAddress`. @@ -55,10 +55,10 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.bind` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - to: The `SocketAddress` to which this `Channel` should bind. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - to: The `SocketAddress` to which this `Channel` should bind. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func bind(context: ChannelHandlerContext, to: SocketAddress, promise: EventLoopPromise?) /// Called to request that the `Channel` connect to a given `SocketAddress`. @@ -66,10 +66,10 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.connect` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - to: The `SocketAddress` to which the the `Channel` should connect. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - to: The `SocketAddress` to which the the `Channel` should connect. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func connect(context: ChannelHandlerContext, to: SocketAddress, promise: EventLoopPromise?) /// Called to request a write operation. The write operation will write the messages through the @@ -79,10 +79,10 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.write` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - data: The data to write through the `Channel`, wrapped in a `NIOAny`. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - data: The data to write through the `Channel`, wrapped in a `NIOAny`. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func write(context: ChannelHandlerContext, data: NIOAny, promise: EventLoopPromise?) /// Called to request that the `Channel` flush all pending writes. The flush operation will try to flush out all previous written messages @@ -91,8 +91,8 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.flush` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or just /// discard it if the flush should be suppressed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func flush(context: ChannelHandlerContext) /// Called to request that the `Channel` perform a read when data is ready. The read operation will signal that we are ready to read more data. @@ -100,8 +100,8 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.read` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or just /// discard it if the read should be suppressed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func read(context: ChannelHandlerContext) /// Called to request that the `Channel` close itself down. @@ -109,10 +109,10 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.close` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - mode: The `CloseMode` to apply - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - mode: The `CloseMode` to apply + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func close(context: ChannelHandlerContext, mode: CloseMode, promise: EventLoopPromise?) /// Called when an user outbound event is triggered. @@ -120,10 +120,10 @@ public protocol _ChannelOutboundHandler: ChannelHandler { /// This should call `context.triggerUserOutboundEvent` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - event: The triggered event. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - event: The triggered event. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. func triggerUserOutboundEvent(context: ChannelHandlerContext, event: Any, promise: EventLoopPromise?) } @@ -141,41 +141,41 @@ public protocol _ChannelInboundHandler: ChannelHandler { /// /// This should call `context.fireChannelRegistered` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelRegistered(context: ChannelHandlerContext) /// Called when the `Channel` has unregistered from its `EventLoop`, and so will no longer be receiving I/O events. /// /// This should call `context.fireChannelUnregistered` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelUnregistered(context: ChannelHandlerContext) /// Called when the `Channel` has become active, and is able to send and receive data. /// /// This should call `context.fireChannelActive` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelActive(context: ChannelHandlerContext) /// Called when the `Channel` has become inactive and is no longer able to send and receive data. /// /// This should call `context.fireChannelInactive` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelInactive(context: ChannelHandlerContext) /// Called when some data has been read from the remote peer. /// /// This should call `context.fireChannelRead` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - data: The data read from the remote peer, wrapped in a `NIOAny`. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - data: The data read from the remote peer, wrapped in a `NIOAny`. func channelRead(context: ChannelHandlerContext, data: NIOAny) /// Called when the `Channel` has completed its current read loop, either because no more data is available to read from the transport at this time, or because the `Channel` needs to yield to the event loop to process other I/O events for other `Channel`s. @@ -183,8 +183,8 @@ public protocol _ChannelInboundHandler: ChannelHandler { /// /// This should call `context.fireChannelReadComplete` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelReadComplete(context: ChannelHandlerContext) /// The writability state of the `Channel` has changed, either because it has buffered more data than the writability high water mark, or because the amount of buffered data has dropped below the writability low water mark. @@ -192,26 +192,26 @@ public protocol _ChannelInboundHandler: ChannelHandler { /// /// This should call `context.fireChannelWritabilityChanged` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. func channelWritabilityChanged(context: ChannelHandlerContext) /// Called when a user inbound event has been triggered. /// /// This should call `context.fireUserInboundEventTriggered` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - event: The event. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - event: The event. func userInboundEventTriggered(context: ChannelHandlerContext, event: Any) /// An error was encountered earlier in the inbound `ChannelPipeline`. /// /// This should call `context.fireErrorCaught` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the error. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - error: The `Error` that was encountered. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - error: The `Error` that was encountered. func errorCaught(context: ChannelHandlerContext, error: Error) } @@ -314,7 +314,7 @@ extension _ChannelInboundHandler { /// A `RemovableChannelHandler` is required to remove itself from the `ChannelPipeline` (using /// `ChannelHandlerContext.leavePipeline`) as soon as possible. /// -/// - note: When a `Channel` gets torn down, every `ChannelHandler` in the `Channel`'s `ChannelPipeline` will be +/// - Note: When a `Channel` gets torn down, every `ChannelHandler` in the `Channel`'s `ChannelPipeline` will be /// removed from the `ChannelPipeline`. Those removals however happen synchronously and are not going through /// the methods of this protocol. public protocol RemovableChannelHandler: ChannelHandler { @@ -324,10 +324,10 @@ public protocol RemovableChannelHandler: ChannelHandler { /// invocation of this method and the call to `ChannelHandlerContext.leavePipeline` that triggers the actual /// removal. /// - /// - note: Like the other `ChannelHandler` methods, this method should not be invoked by the user directly. To + /// - Note: Like the other `ChannelHandler` methods, this method should not be invoked by the user directly. To /// remove a `RemovableChannelHandler` from the `ChannelPipeline`, use `ChannelPipeline.removeHandler`. /// - /// - parameters: + /// - Parameters: /// - context: The `ChannelHandlerContext` of the `RemovableChannelHandler` to be removed from the `ChannelPipeline`. /// - removalToken: The removal token to hand to `ChannelHandlerContext.leavePipeline` to trigger the actual /// removal from the `ChannelPipeline`. diff --git a/Sources/NIOCore/ChannelHandlers.swift b/Sources/NIOCore/ChannelHandlers.swift index 2fd1d57eb3..8e0da681ee 100644 --- a/Sources/NIOCore/ChannelHandlers.swift +++ b/Sources/NIOCore/ChannelHandlers.swift @@ -33,8 +33,8 @@ public final class AcceptBackoffHandler: ChannelDuplexHandler, RemovableChannelH /// Create a new instance /// - /// - parameters: - /// - backoffProvider: returns a `TimeAmount` which will be the amount of time to wait before attempting another `read`. + /// - Parameters: + /// - backoffProvider: returns a `TimeAmount` which will be the amount of time to wait before attempting another `read`. public init(backoffProvider: @escaping (IOError) -> TimeAmount? = AcceptBackoffHandler.defaultBackoffProvider) { self.backoffProvider = backoffProvider self.nextReadDeadlineNS = nil @@ -44,9 +44,9 @@ public final class AcceptBackoffHandler: ChannelDuplexHandler, RemovableChannelH /// Create a new instance /// - /// - parameters: - /// - shouldForwardIOErrorCaught: A boolean indicating if a caught IOError should be forwarded. - /// - backoffProvider: returns a `TimeAmount` which will be the amount of time to wait before attempting another `read`. + /// - Parameters: + /// - shouldForwardIOErrorCaught: A boolean indicating if a caught IOError should be forwarded. + /// - backoffProvider: returns a `TimeAmount` which will be the amount of time to wait before attempting another `read`. public init( shouldForwardIOErrorCaught: Bool, backoffProvider: @escaping (IOError) -> TimeAmount? = AcceptBackoffHandler.defaultBackoffProvider diff --git a/Sources/NIOCore/ChannelInvoker.swift b/Sources/NIOCore/ChannelInvoker.swift index c52847bc28..8d831cac34 100644 --- a/Sources/NIOCore/ChannelInvoker.swift +++ b/Sources/NIOCore/ChannelInvoker.swift @@ -17,22 +17,22 @@ public protocol ChannelOutboundInvoker { /// Register on an `EventLoop` and so have all its IO handled. /// - /// - parameters: - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. func register(promise: EventLoopPromise?) /// Bind to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should bind the `Channel`. - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - to: the `SocketAddress` to which we should bind the `Channel`. + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. func bind(to: SocketAddress, promise: EventLoopPromise?) /// Connect to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should connect the `Channel`. - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - to: the `SocketAddress` to which we should connect the `Channel`. + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. func connect(to: SocketAddress, promise: EventLoopPromise?) @@ -41,9 +41,9 @@ public protocol ChannelOutboundInvoker { /// Be aware that to be sure that data is really written to the remote peer you need to call `flush` or use `writeAndFlush`. /// Calling `write` multiple times and then `flush` may allow the `Channel` to `write` multiple data objects to the remote peer with one syscall. /// - /// - parameters: - /// - data: the data to write - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - data: the data to write + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. @available( *, @@ -57,9 +57,9 @@ public protocol ChannelOutboundInvoker { /// Shortcut for calling `write` and `flush`. /// - /// - parameters: - /// - data: the data to write - /// - promise: the `EventLoopPromise` that will be notified once the `write` operation completes, + /// - Parameters: + /// - data: the data to write + /// - promise: the `EventLoopPromise` that will be notified once the `write` operation completes, /// or `nil` if not interested in the outcome of the operation. @available( *, @@ -77,16 +77,17 @@ public protocol ChannelOutboundInvoker { /// Close the `Channel` and so the connection if one exists. /// - /// - parameters: - /// - mode: the `CloseMode` that is used - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - mode: the `CloseMode` that is used + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. func close(mode: CloseMode, promise: EventLoopPromise?) /// Trigger a custom user outbound event which will flow through the `ChannelPipeline`. /// - /// - parameters: - /// - promise: the `EventLoopPromise` that will be notified once the operation completes, + /// - Parameters: + /// - event: The event itself. + /// - promise: the `EventLoopPromise` that will be notified once the operation completes, /// or `nil` if not interested in the outcome of the operation. @preconcurrency func triggerUserOutboundEvent(_ event: Any & Sendable, promise: EventLoopPromise?) @@ -96,14 +97,16 @@ public protocol ChannelOutboundInvoker { } /// Extra `ChannelOutboundInvoker` methods. Each method that returns a `EventLoopFuture` will just do the following: -/// - create a new `EventLoopPromise` -/// - call the corresponding method that takes a `EventLoopPromise` -/// - return `EventLoopPromise.futureResult` +/// - create a new `EventLoopPromise` +/// - call the corresponding method that takes a `EventLoopPromise` +/// - return `EventLoopPromise.futureResult` extension ChannelOutboundInvoker { /// Register on an `EventLoop` and so have all its IO handled. - /// - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. public func register(file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { let promise = makePromise(file: file, line: line) register(promise: promise) @@ -111,9 +114,11 @@ extension ChannelOutboundInvoker { } /// Bind to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should bind the `Channel`. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - address: the `SocketAddress` to which we should bind the `Channel`. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. public func bind( to address: SocketAddress, file: StaticString = #fileID, @@ -125,9 +130,11 @@ extension ChannelOutboundInvoker { } /// Connect to a `SocketAddress`. - /// - parameters: - /// - to: the `SocketAddress` to which we should connect the `Channel`. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - address: the `SocketAddress` to which we should connect the `Channel`. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. public func connect( to address: SocketAddress, file: StaticString = #fileID, @@ -143,9 +150,11 @@ extension ChannelOutboundInvoker { /// Be aware that to be sure that data is really written to the remote peer you need to call `flush` or use `writeAndFlush`. /// Calling `write` multiple times and then `flush` may allow the `Channel` to `write` multiple data objects to the remote peer with one syscall. /// - /// - parameters: - /// - data: the data to write - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - data: the data to write + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. @available( *, deprecated, @@ -159,9 +168,11 @@ extension ChannelOutboundInvoker { /// Shortcut for calling `write` and `flush`. /// - /// - parameters: - /// - data: the data to write - /// - returns: the future which will be notified once the `write` operation completes. + /// - Parameters: + /// - data: the data to write + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the `write` operation completes. @available( *, deprecated, @@ -176,9 +187,11 @@ extension ChannelOutboundInvoker { /// Close the `Channel` and so the connection if one exists. /// - /// - parameters: - /// - mode: the `CloseMode` that is used - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - mode: the `CloseMode` that is used + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. public func close(mode: CloseMode = .all, file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { let promise = makePromise(file: file, line: line) @@ -188,9 +201,11 @@ extension ChannelOutboundInvoker { /// Trigger a custom user outbound event which will flow through the `ChannelPipeline`. /// - /// - parameters: - /// - event: the event itself. - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - event: the event itself. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. @preconcurrency public func triggerUserOutboundEvent( _ event: Any & Sendable, @@ -230,8 +245,8 @@ public protocol ChannelInboundInvoker { /// Called once there is some data read for a `Channel` that needs processing. /// - /// - parameters: - /// - data: the data that was read and is ready to be processed. + /// - Parameters: + /// - data: the data that was read and is ready to be processed. @available( *, deprecated, @@ -257,14 +272,14 @@ public protocol ChannelInboundInvoker { /// Be aware that for inbound operations this method is called while for outbound operations defined in `ChannelOutboundInvoker` /// the `EventLoopFuture` or `EventLoopPromise` will be notified. /// - /// - parameters: - /// - error: the error we encountered. + /// - Parameters: + /// - error: the error we encountered. func fireErrorCaught(_ error: Error) /// Trigger a custom user inbound event which will flow through the `ChannelPipeline`. /// - /// - parameters: - /// - event: the event itself. + /// - Parameters: + /// - event: the event itself. @preconcurrency func fireUserInboundEventTriggered(_ event: Any & Sendable) } diff --git a/Sources/NIOCore/ChannelOption.swift b/Sources/NIOCore/ChannelOption.swift index bec809b381..17109fa989 100644 --- a/Sources/NIOCore/ChannelOption.swift +++ b/Sources/NIOCore/ChannelOption.swift @@ -95,9 +95,9 @@ extension ChannelOptions { #if !os(Windows) /// Create a new `SocketOption`. /// - /// - parameters: - /// - level: The level for the option as defined in `man setsockopt`, e.g. SO_SOCKET. - /// - name: The name of the option as defined in `man setsockopt`, e.g. `SO_REUSEADDR`. + /// - Parameters: + /// - level: The level for the option as defined in `man setsockopt`, e.g. SO_SOCKET. + /// - name: The name of the option as defined in `man setsockopt`, e.g. `SO_REUSEADDR`. public init(level: SocketOptionLevel, name: SocketOptionName) { self.optionLevel = NIOBSDSocket.OptionLevel(rawValue: CInt(level)) self.optionName = NIOBSDSocket.Option(rawValue: CInt(name)) @@ -106,9 +106,9 @@ extension ChannelOptions { /// Create a new `SocketOption`. /// - /// - parameters: - /// - level: The level for the option as defined in `man setsockopt`, e.g. SO_SOCKET. - /// - name: The name of the option as defined in `man setsockopt`, e.g. `SO_REUSEADDR`. + /// - Parameters: + /// - level: The level for the option as defined in `man setsockopt`, e.g. SO_SOCKET. + /// - name: The name of the option as defined in `man setsockopt`, e.g. `SO_REUSEADDR`. public init(level: NIOBSDSocket.OptionLevel, name: NIOBSDSocket.Option) { self.optionLevel = level self.optionName = name @@ -241,7 +241,7 @@ extension ChannelOptions { /// /// Valid initialization is restricted to `1 <= low <= high`. /// - /// - parameters: + /// - Parameters: /// - low: The low watermark. /// - high: The high watermark. public init(low: Int, high: Int) { @@ -484,9 +484,9 @@ extension ChannelOptions { /// Add `Options`, a `ChannelOption` to the `ChannelOptions.Storage`. /// - /// - parameters: - /// - key: the key for the option - /// - value: the value for the option + /// - Parameters: + /// - newKey: the key for the option + /// - newValue: the value for the option @inlinable public mutating func append(key newKey: Option, value newValue: Option.Value) { @Sendable @@ -512,9 +512,9 @@ extension ChannelOptions { /// Apply all stored `ChannelOption`s to `Channel`. /// - /// - parameters: + /// - Parameters: /// - channel: The `Channel` to apply the `ChannelOption`s to - /// - returns: + /// - Returns: /// - An `EventLoopFuture` that is fulfilled when all `ChannelOption`s have been applied to the `Channel`. public func applyAllChannelOptions(to channel: Channel) -> EventLoopFuture { let applyPromise = channel.eventLoop.makePromise(of: Void.self) @@ -557,8 +557,8 @@ extension ChannelOptions { /// from the ``ChannelOptions/Storage``, as if none had been added. This is useful in rare /// cases where a bootstrap knows that some configuration must purge options of a certain kind. /// - /// - parameters: - /// - key: The ``ChannelOption`` to remove. + /// - Parameters: + /// - key: The ``ChannelOption`` to remove. public mutating func remove(key: Option) { self._storage.removeAll(where: { existingKey, _ in (existingKey as? Option) == key diff --git a/Sources/NIOCore/ChannelPipeline.swift b/Sources/NIOCore/ChannelPipeline.swift index 775cd59a5e..3db4a88abd 100644 --- a/Sources/NIOCore/ChannelPipeline.swift +++ b/Sources/NIOCore/ChannelPipeline.swift @@ -150,7 +150,7 @@ public final class ChannelPipeline: ChannelInvoker { /// The `Channel` that this `ChannelPipeline` belongs to. /// - /// - note: This will be nil after the channel has closed + /// - Note: This will be nil after the channel has closed private var _channel: Optional /// The `Channel` that this `ChannelPipeline` belongs to. @@ -162,11 +162,11 @@ public final class ChannelPipeline: ChannelInvoker { /// Add a `ChannelHandler` to the `ChannelPipeline`. /// - /// - parameters: - /// - name: the name to use for the `ChannelHandler` when it's added. If none is specified it will generate a name. - /// - handler: the `ChannelHandler` to add - /// - position: The position in the `ChannelPipeline` to add `handler`. Defaults to `.last`. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was added. + /// - Parameters: + /// - name: the name to use for the `ChannelHandler` when it's added. If none is specified it will generate a name. + /// - handler: the `ChannelHandler` to add + /// - position: The position in the `ChannelPipeline` to add `handler`. Defaults to `.last`. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was added. @preconcurrency public func addHandler( _ handler: ChannelHandler & Sendable, @@ -190,11 +190,11 @@ public final class ChannelPipeline: ChannelInvoker { /// /// May only be called from on the event loop. /// - /// - parameters: - /// - handler: the `ChannelHandler` to add - /// - name: the name to use for the `ChannelHandler` when it's added. If none is specified a name will be generated. - /// - position: The position in the `ChannelPipeline` to add `handler`. Defaults to `.last`. - /// - returns: the result of adding this handler - either success or failure with an error code if this could not be completed. + /// - Parameters: + /// - handler: the `ChannelHandler` to add + /// - name: the name to use for the `ChannelHandler` when it's added. If none is specified a name will be generated. + /// - position: The position in the `ChannelPipeline` to add `handler`. Defaults to `.last`. + /// - Returns: the result of adding this handler - either success or failure with an error code if this could not be completed. fileprivate func addHandlerSync( _ handler: ChannelHandler, name: String? = nil, @@ -246,14 +246,14 @@ public final class ChannelPipeline: ChannelInvoker { /// This will search the pipeline for `relativeHandler` and, if it cannot find it, will fail /// `promise` with `ChannelPipelineError.notFound`. /// - /// - parameters: - /// - name: The name to use for the `ChannelHandler` when its added. If none is specified, a name will be + /// - Parameters: + /// - name: The name to use for the `ChannelHandler` when its added. If none is specified, a name will be /// automatically generated. - /// - handler: The `ChannelHandler` to add. - /// - relativeHandler: The `ChannelHandler` already in the `ChannelPipeline` that `handler` will be + /// - handler: The `ChannelHandler` to add. + /// - relativeHandler: The `ChannelHandler` already in the `ChannelPipeline` that `handler` will be /// inserted relative to. - /// - operation: A callback that will insert `handler` relative to `relativeHandler`. - /// - returns: the result of adding this handler - either success or failure with an error code if this could not be completed. + /// - operation: A callback that will insert `handler` relative to `relativeHandler`. + /// - Returns: the result of adding this handler - either success or failure with an error code if this could not be completed. private func add0( name: String?, handler: ChannelHandler, @@ -280,14 +280,14 @@ public final class ChannelPipeline: ChannelInvoker { /// This method is more efficient than the one that takes a `relativeHandler` as it does not need to /// search the pipeline for the insertion point. It should be used whenever possible. /// - /// - parameters: - /// - name: The name to use for the `ChannelHandler` when its added. If none is specified, a name will be + /// - Parameters: + /// - name: The name to use for the `ChannelHandler` when its added. If none is specified, a name will be /// automatically generated. - /// - handler: The `ChannelHandler` to add. - /// - relativeContext: The `ChannelHandlerContext` already in the `ChannelPipeline` that `handler` will be + /// - handler: The `ChannelHandler` to add. + /// - relativeContext: The `ChannelHandlerContext` already in the `ChannelPipeline` that `handler` will be /// inserted relative to. - /// - operation: A callback that will insert `handler` relative to `relativeHandler`. - /// - returns: the result of adding this handler - either success or failure with an error code if this could not be completed. + /// - operation: A callback that will insert `handler` relative to `relativeHandler`. + /// - Returns: the result of adding this handler - either success or failure with an error code if this could not be completed. private func add0( name: String?, handler: ChannelHandler, @@ -313,9 +313,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Must be called from within the event loop thread, as it synchronously manipulates the /// `ChannelHandlerContext`s on the `ChannelPipeline`. /// - /// - parameters: - /// - new: The `ChannelHandlerContext` to add to the pipeline. - /// - existing: The `ChannelHandlerContext` that `new` will be added after. + /// - Parameters: + /// - new: The `ChannelHandlerContext` to add to the pipeline. + /// - existing: The `ChannelHandlerContext` that `new` will be added after. private func add0(context new: ChannelHandlerContext, after existing: ChannelHandlerContext) { self.eventLoop.assertInEventLoop() @@ -332,9 +332,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Must be called from within the event loop thread, as it synchronously manipulates the /// `ChannelHandlerContext`s on the `ChannelPipeline`. /// - /// - parameters: - /// - new: The `ChannelHandlerContext` to add to the pipeline. - /// - existing: The `ChannelHandlerContext` that `new` will be added before. + /// - Parameters: + /// - new: The `ChannelHandlerContext` to add to the pipeline. + /// - existing: The `ChannelHandlerContext` that `new` will be added before. private func add0(context new: ChannelHandlerContext, before existing: ChannelHandlerContext) { self.eventLoop.assertInEventLoop() @@ -347,9 +347,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - handler: the `ChannelHandler` to remove. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - handler: the `ChannelHandler` to remove. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. @preconcurrency public func removeHandler(_ handler: RemovableChannelHandler & Sendable) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self) @@ -359,9 +359,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. public func removeHandler(name: String) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self) self.removeHandler(name: name, promise: promise) @@ -370,9 +370,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. @available( *, deprecated, @@ -386,9 +386,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - handler: the `ChannelHandler` to remove. - /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. + /// - Parameters: + /// - handler: the `ChannelHandler` to remove. + /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. @preconcurrency public func removeHandler(_ handler: RemovableChannelHandler & Sendable, promise: EventLoopPromise?) { @Sendable @@ -407,9 +407,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. - /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. + /// - Parameters: + /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. + /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. public func removeHandler(name: String, promise: EventLoopPromise?) { @Sendable func removeHandler0() { @@ -427,9 +427,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. - /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. + /// - Parameters: + /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. + /// - promise: An `EventLoopPromise` that will complete when the `ChannelHandler` is removed. @available( *, deprecated, @@ -459,9 +459,9 @@ public final class ChannelPipeline: ChannelInvoker { /// Returns the `ChannelHandlerContext` that belongs to a `ChannelHandler`. /// - /// - parameters: - /// - handler: the `ChannelHandler` for which the `ChannelHandlerContext` should be returned - /// - returns: the `EventLoopFuture` which will be notified once the the operation completes. + /// - Parameters: + /// - handler: the `ChannelHandler` for which the `ChannelHandlerContext` should be returned + /// - Returns: the `EventLoopFuture` which will be notified once the the operation completes. @available( *, deprecated, @@ -485,18 +485,18 @@ public final class ChannelPipeline: ChannelInvoker { /// Synchronously returns the `ChannelHandlerContext` that belongs to a `ChannelHandler`. /// /// - Important: This must be called on the `EventLoop`. - /// - parameters: - /// - handler: the `ChannelHandler` for which the `ChannelHandlerContext` should be returned - /// - returns: the `ChannelHandlerContext` that belongs to the `ChannelHandler`, if one exists. + /// - Parameters: + /// - handler: the `ChannelHandler` for which the `ChannelHandlerContext` should be returned + /// - Returns: the `ChannelHandlerContext` that belongs to the `ChannelHandler`, if one exists. fileprivate func contextSync(handler: ChannelHandler) -> Result { self._contextSync({ $0.handler === handler }) } /// Returns the `ChannelHandlerContext` that belongs to a `ChannelHandler`. /// - /// - parameters: - /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. - /// - returns: the `EventLoopFuture` which will be notified once the the operation completes. + /// - Parameters: + /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. + /// - Returns: the `EventLoopFuture` which will be notified once the the operation completes. public func context(name: String) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: ChannelHandlerContext.self) @@ -526,9 +526,9 @@ public final class ChannelPipeline: ChannelInvoker { /// If multiple channel handlers of the same type are present in the pipeline, returns the context /// belonging to the first such handler. /// - /// - parameters: - /// - handlerType: The type of the handler to search for. - /// - returns: the `EventLoopFuture` which will be notified once the the operation completes. + /// - Parameters: + /// - handlerType: The type of the handler to search for. + /// - Returns: the `EventLoopFuture` which will be notified once the the operation completes. @inlinable public func context(handlerType: Handler.Type) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: ChannelHandlerContext.self) @@ -596,9 +596,9 @@ public final class ChannelPipeline: ChannelInvoker { /// /// This skips head and tail (as these are internal and should not be accessible by the user). /// - /// - parameters: - /// - body: The predicate to execute per `ChannelHandlerContext` in the `ChannelPipeline`. - /// - returns: The first `ChannelHandlerContext` that matches or `nil` if none did. + /// - Parameters: + /// - body: The predicate to execute per `ChannelHandlerContext` in the `ChannelPipeline`. + /// - Returns: The first `ChannelHandlerContext` that matches or `nil` if none did. private func contextForPredicate0(_ body: (ChannelHandlerContext) -> Bool) -> ChannelHandlerContext? { var curCtx: ChannelHandlerContext? = self.head?.next while let context = curCtx, context !== self.tail { @@ -1042,7 +1042,7 @@ public final class ChannelPipeline: ChannelInvoker { /// directly: it is only intended for use with custom `Channel` implementations. Users should always use /// `channel.pipeline` to access the `ChannelPipeline` for a `Channel`. /// - /// - parameters: + /// - Parameters: /// - channel: The `Channel` this `ChannelPipeline` is created for. public init(channel: Channel) { self._channel = channel @@ -1071,11 +1071,11 @@ extension ChannelPipeline { /// Adds the provided channel handlers to the pipeline in the order given, taking account /// of the behaviour of `ChannelHandler.add(first:)`. /// - /// - parameters: - /// - handlers: The array of `ChannelHandler`s to be added. - /// - position: The position in the `ChannelPipeline` to add `handlers`. Defaults to `.last`. + /// - Parameters: + /// - handlers: The array of `ChannelHandler`s to be added. + /// - position: The position in the `ChannelPipeline` to add `handlers`. Defaults to `.last`. /// - /// - returns: A future that will be completed when all of the supplied `ChannelHandler`s were added. + /// - Returns: A future that will be completed when all of the supplied `ChannelHandler`s were added. @preconcurrency public func addHandlers( _ handlers: [ChannelHandler & Sendable], @@ -1097,11 +1097,11 @@ extension ChannelPipeline { /// Adds the provided channel handlers to the pipeline in the order given, taking account /// of the behaviour of `ChannelHandler.add(first:)`. /// - /// - parameters: - /// - handlers: One or more `ChannelHandler`s to be added. - /// - position: The position in the `ChannelPipeline` to add `handlers`. Defaults to `.last`. + /// - Parameters: + /// - handlers: One or more `ChannelHandler`s to be added. + /// - position: The position in the `ChannelPipeline` to add `handlers`. Defaults to `.last`. /// - /// - returns: A future that will be completed when all of the supplied `ChannelHandler`s were added. + /// - Returns: A future that will be completed when all of the supplied `ChannelHandler`s were added. @preconcurrency public func addHandlers( _ handlers: (ChannelHandler & Sendable)..., @@ -1219,9 +1219,9 @@ extension ChannelPipeline { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - handler: the `ChannelHandler` to remove. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - handler: the `ChannelHandler` to remove. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. public func removeHandler(_ handler: RemovableChannelHandler) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self) self.removeHandler(handler, promise: promise) @@ -1230,9 +1230,9 @@ extension ChannelPipeline { /// Remove a ``ChannelHandler`` from the ``ChannelPipeline``. /// - /// - parameters: - /// - handler: the ``ChannelHandler`` to remove. - /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. + /// - Parameters: + /// - handler: the ``ChannelHandler`` to remove. + /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. public func removeHandler(_ handler: RemovableChannelHandler, promise: EventLoopPromise?) { switch self._pipeline.contextSync(handler: handler) { case .success(let context): @@ -1244,9 +1244,9 @@ extension ChannelPipeline { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. public func removeHandler(name: String) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self) self.removeHandler(name: name, promise: promise) @@ -1255,9 +1255,9 @@ extension ChannelPipeline { /// Remove a ``ChannelHandler`` from the ``ChannelPipeline``. /// - /// - parameters: - /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. - /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. + /// - Parameters: + /// - name: the name that was used to add the `ChannelHandler` to the `ChannelPipeline` before. + /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. public func removeHandler(name: String, promise: EventLoopPromise?) { switch self._pipeline.contextSync(name: name) { case .success(let context): @@ -1269,9 +1269,9 @@ extension ChannelPipeline { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. - /// - returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. + /// - Parameters: + /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. + /// - Returns: the `EventLoopFuture` which will be notified once the `ChannelHandler` was removed. public func removeHandler(context: ChannelHandlerContext) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self) self.removeHandler(context: context, promise: promise) @@ -1280,9 +1280,9 @@ extension ChannelPipeline { /// Remove a `ChannelHandler` from the `ChannelPipeline`. /// - /// - parameters: - /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. - /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. + /// - Parameters: + /// - context: the `ChannelHandlerContext` that belongs to `ChannelHandler` that should be removed. + /// - promise: an ``EventLoopPromise`` to notify when the ``ChannelHandler`` was removed. public func removeHandler(context: ChannelHandlerContext, promise: EventLoopPromise?) { if context.handler is RemovableChannelHandler { context.startUserTriggeredRemoval(promise: promise) @@ -1313,7 +1313,7 @@ extension ChannelPipeline { /// Returns the `ChannelHandlerContext` for the handler of given type, if one exists. /// /// - Important: This *must* be called on the event loop. - /// - Parameter name: The name of the handler whose context is being fetched. + /// - Parameter handlerType: The type of the handler to search for. /// - Returns: The `ChannelHandlerContext` associated with the handler. @inlinable public func context(handlerType: Handler.Type) throws -> ChannelHandlerContext { @@ -1708,28 +1708,28 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `channelRegistered` event to the next (inbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `channelRegistered` event using this method at the right point in time, that is usually when received. + /// - Note: For correct operation it is very important to forward any `channelRegistered` event using this method at the right point in time, that is usually when received. public func fireChannelRegistered() { self.next?.invokeChannelRegistered() } /// Send a `channelUnregistered` event to the next (inbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `channelUnregistered` event using this method at the right point in time, that is usually when received. + /// - Note: For correct operation it is very important to forward any `channelUnregistered` event using this method at the right point in time, that is usually when received. public func fireChannelUnregistered() { self.next?.invokeChannelUnregistered() } /// Send a `channelActive` event to the next (inbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `channelActive` event using this method at the right point in time, that is often when received. + /// - Note: For correct operation it is very important to forward any `channelActive` event using this method at the right point in time, that is often when received. public func fireChannelActive() { self.next?.invokeChannelActive() } /// Send a `channelInactive` event to the next (inbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `channelInactive` event using this method at the right point in time, that is often when received. + /// - Note: For correct operation it is very important to forward any `channelInactive` event using this method at the right point in time, that is often when received. public func fireChannelInactive() { self.next?.invokeChannelInactive() } @@ -1746,7 +1746,7 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `writabilityChanged` event to the next (inbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `writabilityChanged` event using this method at the right point in time, that is usually when received. + /// - Note: For correct operation it is very important to forward any `writabilityChanged` event using this method at the right point in time, that is usually when received. public func fireChannelWritabilityChanged() { self.next?.invokeChannelWritabilityChanged() } @@ -1772,7 +1772,7 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `register` event to the next (outbound) `ChannelHandler` in the `ChannelPipeline`. /// - /// - note: For correct operation it is very important to forward any `register` event using this method at the right point in time, that is usually when received. + /// - Note: For correct operation it is very important to forward any `register` event using this method at the right point in time, that is usually when received. public func register(promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeRegister(promise: promise) @@ -1784,9 +1784,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `bind` event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// When the `bind` event reaches the `HeadChannelHandler` a `ServerSocketChannel` will be bound. /// - /// - parameters: - /// - address: The address to bind to. - /// - promise: The promise fulfilled when the socket is bound or failed if it cannot be bound. + /// - Parameters: + /// - address: The address to bind to. + /// - promise: The promise fulfilled when the socket is bound or failed if it cannot be bound. public func bind(to address: SocketAddress, promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeBind(to: address, promise: promise) @@ -1798,9 +1798,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `connect` event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// When the `connect` event reaches the `HeadChannelHandler` a `SocketChannel` will be connected. /// - /// - parameters: - /// - address: The address to connect to. - /// - promise: The promise fulfilled when the socket is connected or failed if it cannot be connected. + /// - Parameters: + /// - address: The address to connect to. + /// - promise: The promise fulfilled when the socket is connected or failed if it cannot be connected. public func connect(to address: SocketAddress, promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeConnect(to: address, promise: promise) @@ -1813,9 +1813,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// When the `write` event reaches the `HeadChannelHandler` the data will be enqueued to be written on the next /// `flush` event. /// - /// - parameters: - /// - data: The data to write, should be of type `ChannelOutboundHandler.OutboundOut`. - /// - promise: The promise fulfilled when the data has been written or failed if it cannot be written. + /// - Parameters: + /// - data: The data to write, should be of type `ChannelOutboundHandler.OutboundOut`. + /// - promise: The promise fulfilled when the data has been written or failed if it cannot be written. public func write(_ data: NIOAny, promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeWrite(data, promise: promise) @@ -1827,9 +1827,6 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `flush` event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// When the `flush` event reaches the `HeadChannelHandler` the data previously enqueued will be attempted to be /// written to the socket. - /// - /// - parameters: - /// - promise: The promise fulfilled when the previously written data been flushed or failed if it cannot be flushed. public func flush() { if let outboundNext = self.prev { outboundNext.invokeFlush() @@ -1840,9 +1837,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// When the `write` event reaches the `HeadChannelHandler` the data will be enqueued to be written when the `flush` /// also reaches the `HeadChannelHandler`. /// - /// - parameters: - /// - data: The data to write, should be of type `ChannelOutboundHandler.OutboundOut`. - /// - promise: The promise fulfilled when the previously written data been written and flushed or if that failed. + /// - Parameters: + /// - data: The data to write, should be of type `ChannelOutboundHandler.OutboundOut`. + /// - promise: The promise fulfilled when the previously written data been written and flushed or if that failed. public func writeAndFlush(_ data: NIOAny, promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeWriteAndFlush(data, promise: promise) @@ -1864,9 +1861,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a `close` event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// When the `close` event reaches the `HeadChannelHandler` the socket will be closed. /// - /// - parameters: - /// - mode: The `CloseMode` to use. - /// - promise: The promise fulfilled when the `Channel` has been closed or failed if it the closing failed. + /// - Parameters: + /// - mode: The `CloseMode` to use. + /// - promise: The promise fulfilled when the `Channel` has been closed or failed if it the closing failed. public func close(mode: CloseMode = .all, promise: EventLoopPromise?) { if let outboundNext = self.prev { outboundNext.invokeClose(mode: mode, promise: promise) @@ -1877,9 +1874,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a user event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// - /// - parameters: - /// - event: The user event to send. - /// - promise: The promise fulfilled when the user event has been sent or failed if it couldn't be sent. + /// - Parameters: + /// - event: The user event to send. + /// - promise: The promise fulfilled when the user event has been sent or failed if it couldn't be sent. @available(*, deprecated) @_disfavoredOverload public func triggerUserOutboundEvent(_ event: Any & Sendable, promise: EventLoopPromise?) { @@ -1888,9 +1885,9 @@ public final class ChannelHandlerContext: ChannelInvoker { /// Send a user event to the next outbound `ChannelHandler` in the `ChannelPipeline`. /// - /// - parameters: - /// - event: The user event to send. - /// - promise: The promise fulfilled when the user event has been sent or failed if it couldn't be sent. + /// - Parameters: + /// - event: The user event to send. + /// - promise: The promise fulfilled when the user event has been sent or failed if it couldn't be sent. public func triggerUserOutboundEvent(_ event: Any, promise: EventLoopPromise?) { self._triggerUserOutboundEvent(event, promise: promise) } @@ -2110,9 +2107,11 @@ extension ChannelHandlerContext { /// Be aware that to be sure that data is really written to the remote peer you need to call `flush` or use `writeAndFlush`. /// Calling `write` multiple times and then `flush` may allow the `Channel` to `write` multiple data objects to the remote peer with one syscall. /// - /// - parameters: - /// - data: the data to write - /// - returns: the future which will be notified once the operation completes. + /// - Parameters: + /// - data: the data to write + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the operation completes. public func write(_ data: NIOAny, file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self, file: file, line: line) self.write(data, promise: promise) @@ -2121,9 +2120,11 @@ extension ChannelHandlerContext { /// Shortcut for calling `write` and `flush`. /// - /// - parameters: - /// - data: the data to write - /// - returns: the future which will be notified once the `write` operation completes. + /// - Parameters: + /// - data: the data to write + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - Returns: the future which will be notified once the `write` operation completes. public func writeAndFlush(_ data: NIOAny, file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { let promise = self.eventLoop.makePromise(of: Void.self, file: file, line: line) @@ -2145,10 +2146,10 @@ extension ChannelHandlerContext { /// Synchronously remove the `ChannelHandler` with the given `ChannelHandlerContext`. /// - /// - note: This function must only be used from a `RemovableChannelHandler` to remove itself. Calling this method + /// - Note: This function must only be used from a `RemovableChannelHandler` to remove itself. Calling this method /// on any other `ChannelHandlerContext` leads to undefined behaviour. /// - /// - parameters: + /// - Parameters: /// - removalToken: The removal token received from `RemovableChannelHandler.removeHandler` public func leavePipeline(removalToken: RemovalToken) { self.eventLoop.preconditionInEventLoop() @@ -2261,8 +2262,8 @@ extension ChannelPipeline: CustomDebugStringConvertible { /// Returns the first `ChannelHandler` of the given type. /// - /// - parameters: - /// - type: the type of `ChannelHandler` to return. + /// - Parameters: + /// - type: the type of `ChannelHandler` to return. @inlinable public func handler(type _: Handler.Type) -> EventLoopFuture { self.context(handlerType: Handler.self).map { context in @@ -2280,7 +2281,7 @@ extension ChannelPipeline: CustomDebugStringConvertible { /// /// - Important: This must be called on the `EventLoop`. /// - Parameters: - /// - type: the type of `ChannelHandler` to return. + /// - type: the type of `ChannelHandler` to return. @inlinable // should be fileprivate internal func _handlerSync(type _: Handler.Type) -> Result { self._contextSync(handlerType: Handler.self).map { context in @@ -2407,7 +2408,7 @@ extension ChannelPipeline.SynchronousOperations { /// Retrieve the number of outbound bytes buffered in the `ChannelHandler` associated with the given`ChannelHandlerContext`. /// /// - Parameters: - /// - in: the `ChannelHandlerContext` from which the outbound buffered bytes of the `ChannelHandler` will be retrieved. + /// - context: the `ChannelHandlerContext` from which the outbound buffered bytes of the `ChannelHandler` will be retrieved. /// - Important: This *must* be called on the event loop. /// /// - Returns: The number of bytes currently buffered in the `ChannelHandler` referenced by the `ChannelHandlerContext` parameter `in`. @@ -2429,7 +2430,7 @@ extension ChannelPipeline.SynchronousOperations { /// Retrieve the number of inbound bytes buffered in the `ChannelHandler` associated with the given `ChannelHandlerContext`. /// /// - Parameters: - /// - in: the `ChannelHandlerContext` from which the inbound buffered bytes of the `handler` will be retrieved. + /// - context: the `ChannelHandlerContext` from which the inbound buffered bytes of the `handler` will be retrieved. /// - Important: This *must* be called on the event loop. /// /// - Returns: The number of bytes currently buffered in the `ChannelHandler` referenced by the `ChannelHandlerContext` parameter `in`. diff --git a/Sources/NIOCore/CircularBuffer.swift b/Sources/NIOCore/CircularBuffer.swift index 360b3dfb0d..e9d114b66d 100644 --- a/Sources/NIOCore/CircularBuffer.swift +++ b/Sources/NIOCore/CircularBuffer.swift @@ -60,7 +60,7 @@ public struct CircularBuffer: CustomStringConvertible { /// You may get indices offset from other indices by using `CircularBuffer.index(:offsetBy:)`, /// `CircularBuffer.index(before:)`, or `CircularBuffer.index(after:)`. /// - /// - note: Every index is invalidated as soon as you perform a length-changing operating on the `CircularBuffer` + /// - Note: Every index is invalidated as soon as you perform a length-changing operating on the `CircularBuffer` /// but remains valid when you replace one item by another using the subscript. public struct Index: Comparable, Sendable { @usableFromInline private(set) var _backingIndex: UInt32 @@ -122,7 +122,7 @@ extension CircularBuffer: Collection, MutableCollection { /// collection `c`, calling `c.index(after: i)` returns the same index every /// time. /// - /// - Parameter i: A valid index of the collection. `i` must be less than + /// - Parameter after: A valid index of the collection. `i` must be less than /// `endIndex`. /// - Returns: The index value immediately after `i`. @inlinable @@ -495,9 +495,9 @@ extension CircularBuffer { /// are interested in using this function for performance you *must* test and verify that the optimisation applies /// correctly in your situation. /// - /// - parameters: - /// - index: The index of the object that should be modified. If this index is invalid this function will trap. - /// - modifyFunc: The function to apply to the modified object. + /// - Parameters: + /// - index: The index of the object that should be modified. If this index is invalid this function will trap. + /// - modifyFunc: The function to apply to the modified object. @inlinable public mutating func modify( _ index: Index, diff --git a/Sources/NIOCore/Codec.swift b/Sources/NIOCore/Codec.swift index 730e3e1bc6..acb4fc1394 100644 --- a/Sources/NIOCore/Codec.swift +++ b/Sources/NIOCore/Codec.swift @@ -151,10 +151,10 @@ public protocol ByteToMessageDecoder { /// contains more readable bytes, this method will immediately be invoked again, unless `decodeLast` needs /// to be invoked instead. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. - /// - buffer: The `ByteBuffer` from which we decode. - /// - returns: `DecodingState.continue` if we should continue calling this method or `DecodingState.needMoreData` if it should be called + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. + /// - buffer: The `ByteBuffer` from which we decode. + /// - Returns: `DecodingState.continue` if we should continue calling this method or `DecodingState.needMoreData` if it should be called /// again once more data is present in the `ByteBuffer`. mutating func decode(context: ChannelHandlerContext, buffer: inout ByteBuffer) throws -> DecodingState @@ -168,11 +168,11 @@ public protocol ByteToMessageDecoder { /// or until the input `ByteBuffer` has no more readable bytes. If `DecodingState.continue` is returned and the `ByteBuffer` /// contains more readable bytes, this method will immediately be invoked again. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. - /// - buffer: The `ByteBuffer` from which we decode. - /// - seenEOF: `true` if EOF has been seen. Usually if this is `false` the handler has been removed. - /// - returns: `DecodingState.continue` if we should continue calling this method or `DecodingState.needMoreData` if it should be called + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. + /// - buffer: The `ByteBuffer` from which we decode. + /// - seenEOF: `true` if EOF has been seen. Usually if this is `false` the handler has been removed. + /// - Returns: `DecodingState.continue` if we should continue calling this method or `DecodingState.needMoreData` if it should be called /// again when more data is present in the `ByteBuffer`. mutating func decodeLast( context: ChannelHandlerContext, @@ -182,21 +182,21 @@ public protocol ByteToMessageDecoder { /// Called once this `ByteToMessageDecoder` is removed from the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. mutating func decoderRemoved(context: ChannelHandlerContext) /// Called when this `ByteToMessageDecoder` is added to the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ByteToMessageDecoder` belongs to. mutating func decoderAdded(context: ChannelHandlerContext) /// Determine if the read bytes in the given `ByteBuffer` should be reclaimed and their associated memory freed. /// Be aware that reclaiming memory may involve memory copies and so is not free. /// - /// - parameters: - /// - buffer: The `ByteBuffer` to check + /// - Parameters: + /// - buffer: The `ByteBuffer` to check /// - return: `true` if memory should be reclaimed, `false` otherwise. mutating func shouldReclaimBytes(buffer: ByteBuffer) -> Bool } @@ -212,7 +212,7 @@ public protocol WriteObservingByteToMessageDecoder: ByteToMessageDecoder { /// `write` is called for every incoming `write` incoming to the corresponding `ByteToMessageHandler`. /// - /// - parameters: + /// - Parameters: /// - data: The data that was written. mutating func write(data: OutboundIn) } @@ -483,9 +483,9 @@ public final class ByteToMessageHandler { /// Initialize a `ByteToMessageHandler`. /// - /// - parameters: - /// - decoder: The `ByteToMessageDecoder` to decode the bytes into message. - /// - maximumBufferSize: The maximum number of bytes to aggregate in-memory. + /// - Parameters: + /// - decoder: The `ByteToMessageDecoder` to decode the bytes into message. + /// - maximumBufferSize: The maximum number of bytes to aggregate in-memory. public init(_ decoder: Decoder, maximumBufferSize: Int? = nil) { self.decoder = decoder self.maximumBufferSize = maximumBufferSize @@ -739,9 +739,9 @@ public protocol MessageToByteEncoder { /// Called once there is data to encode. /// - /// - parameters: - /// - data: The data to encode into a `ByteBuffer`. - /// - out: The `ByteBuffer` into which we want to encode. + /// - Parameters: + /// - data: The data to encode into a `ByteBuffer`. + /// - out: The `ByteBuffer` into which we want to encode. func encode(data: OutboundIn, out: inout ByteBuffer) throws } diff --git a/Sources/NIOCore/ConvenienceOptionSupport.swift b/Sources/NIOCore/ConvenienceOptionSupport.swift index 09a6ad7f01..5027dafa17 100644 --- a/Sources/NIOCore/ConvenienceOptionSupport.swift +++ b/Sources/NIOCore/ConvenienceOptionSupport.swift @@ -15,9 +15,9 @@ // MARK: Universal Client Bootstrap extension NIOClientTCPBootstrapProtocol { /// Apply any understood convenience options to the bootstrap, removing them from the set of options if they are consumed. - /// - parameters: - /// - options: The options to try applying - the options applied should be consumed from here. - /// - returns: The updated bootstrap with and options applied. + /// - Parameters: + /// - options: The options to try applying - the options applied should be consumed from here. + /// - Returns: The updated bootstrap with and options applied. public func _applyChannelConvenienceOptions(_ options: inout ChannelOptions.TCPConvenienceOptions) -> Self { // Default is to consume no options and not update self. self diff --git a/Sources/NIOCore/DispatchQueue+WithFuture.swift b/Sources/NIOCore/DispatchQueue+WithFuture.swift index ec9bc03b49..6cc7d33cad 100644 --- a/Sources/NIOCore/DispatchQueue+WithFuture.swift +++ b/Sources/NIOCore/DispatchQueue+WithFuture.swift @@ -24,9 +24,9 @@ extension DispatchQueue { /// } /// try let value = futureResult.wait() /// - /// - parameters: - /// - eventLoop: the `EventLoop` on which to processes the IO / task specified by `callbackMayBlock`. - /// - callbackMayBlock: The scheduled callback for the IO / task. + /// - Parameters: + /// - eventLoop: the `EventLoop` on which to processes the IO / task specified by `callbackMayBlock`. + /// - callbackMayBlock: The scheduled callback for the IO / task. /// - returns a new `EventLoopFuture` with value returned by the `block` parameter. @inlinable @preconcurrency diff --git a/Sources/NIOCore/Docs.docc/ByteBuffer-lengthPrefix.md b/Sources/NIOCore/Docs.docc/ByteBuffer-lengthPrefix.md index 34ba804694..57364f2857 100644 --- a/Sources/NIOCore/Docs.docc/ByteBuffer-lengthPrefix.md +++ b/Sources/NIOCore/Docs.docc/ByteBuffer-lengthPrefix.md @@ -53,8 +53,8 @@ We decided to add the following API to ByteBuffer: ```swift /// - Parameters: -/// - strategy: The strategy to use for encoding the length. -/// - writeData: A closure that takes a buffer, writes some data to it, and returns the number of bytes written. +/// - strategy: The strategy to use for encoding the length. +/// - writeData: A closure that takes a buffer, writes some data to it, and returns the number of bytes written. /// - Returns: Number of total bytes written. This is the length of the written data + the number of bytes used to write the length before it. public mutating func writeLengthPrefixed( strategy: Strategy, diff --git a/Sources/NIOCore/EventLoop.swift b/Sources/NIOCore/EventLoop.swift index 5732a989be..047c06e67e 100644 --- a/Sources/NIOCore/EventLoop.swift +++ b/Sources/NIOCore/EventLoop.swift @@ -209,7 +209,7 @@ public struct EventLoopIterator: Sequence, IteratorProtocol { /// Advances to the next `EventLoop` and returns it, or `nil` if no next element exists. /// - /// - returns: The next `EventLoop` if a next element exists; otherwise, `nil`. + /// - Returns: The next `EventLoop` if a next element exists; otherwise, `nil`. public mutating func next() -> EventLoop? { self.eventLoops.next() } @@ -263,33 +263,35 @@ public protocol EventLoop: EventLoopGroup { /// Submit a given task to be executed by the `EventLoop`. Once the execution is complete the returned `EventLoopFuture` is notified. /// - /// - parameters: - /// - task: The closure that will be submitted to the `EventLoop` for execution. - /// - returns: `EventLoopFuture` that is notified once the task was executed. + /// - Parameters: + /// - task: The closure that will be submitted to the `EventLoop` for execution. + /// - Returns: `EventLoopFuture` that is notified once the task was executed. @preconcurrency func submit(_ task: @escaping @Sendable () throws -> T) -> EventLoopFuture /// Schedule a `task` that is executed by this `EventLoop` at the given time. /// - /// - parameters: - /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - deadline: The instant in time before which the task will not execute. + /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the completion of the task. /// - /// - note: You can only cancel a task before it has started executing. + /// - Note: You can only cancel a task before it has started executing. @discardableResult @preconcurrency func scheduleTask(deadline: NIODeadline, _ task: @escaping @Sendable () throws -> T) -> Scheduled /// Schedule a `task` that is executed by this `EventLoop` after the given amount of time. /// - /// - parameters: - /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - in: The amount of time before which the task will not execute. + /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the completion of the task. /// - /// - note: You can only cancel a task before it has started executing. - /// - note: The `in` value is clamped to a maximum when running on a Darwin-kernel. + /// - Note: You can only cancel a task before it has started executing. + /// - Note: The `in` value is clamped to a maximum when running on a Darwin-kernel. @discardableResult @preconcurrency func scheduleTask(in: TimeAmount, _ task: @escaping @Sendable () throws -> T) -> Scheduled @@ -441,7 +443,7 @@ extension EventLoopGroup { /// Represents a time _interval_. /// -/// - note: `TimeAmount` should not be used to represent a point in time. +/// - Note: `TimeAmount` should not be used to represent a point in time. public struct TimeAmount: Hashable, Sendable { @available(*, deprecated, message: "This typealias doesn't serve any purpose. Please use Int64 directly.") public typealias Value = Int64 @@ -456,9 +458,9 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of nanoseconds. /// - /// - parameters: - /// - amount: the amount of nanoseconds this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of nanoseconds this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. @inlinable public static func nanoseconds(_ amount: Int64) -> TimeAmount { TimeAmount(amount) @@ -466,11 +468,11 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of microseconds. /// - /// - parameters: - /// - amount: the amount of microseconds this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of microseconds this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. /// - /// - note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. + /// - Note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. @inlinable public static func microseconds(_ amount: Int64) -> TimeAmount { TimeAmount(_cappedNanoseconds(amount: amount, multiplier: 1000)) @@ -478,11 +480,11 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of milliseconds. /// - /// - parameters: - /// - amount: the amount of milliseconds this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of milliseconds this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. /// - /// - note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. + /// - Note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. @inlinable public static func milliseconds(_ amount: Int64) -> TimeAmount { TimeAmount(_cappedNanoseconds(amount: amount, multiplier: 1000 * 1000)) @@ -490,11 +492,11 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of seconds. /// - /// - parameters: - /// - amount: the amount of seconds this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of seconds this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. /// - /// - note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. + /// - Note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. @inlinable public static func seconds(_ amount: Int64) -> TimeAmount { TimeAmount(_cappedNanoseconds(amount: amount, multiplier: 1000 * 1000 * 1000)) @@ -502,11 +504,11 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of minutes. /// - /// - parameters: - /// - amount: the amount of minutes this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of minutes this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. /// - /// - note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. + /// - Note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. @inlinable public static func minutes(_ amount: Int64) -> TimeAmount { TimeAmount(_cappedNanoseconds(amount: amount, multiplier: 1000 * 1000 * 1000 * 60)) @@ -514,11 +516,11 @@ public struct TimeAmount: Hashable, Sendable { /// Creates a new `TimeAmount` for the given amount of hours. /// - /// - parameters: - /// - amount: the amount of hours this `TimeAmount` represents. - /// - returns: the `TimeAmount` for the given amount. + /// - Parameters: + /// - amount: the amount of hours this `TimeAmount` represents. + /// - Returns: the `TimeAmount` for the given amount. /// - /// - note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. + /// - Note: returns `TimeAmount(.max)` if the amount overflows when converted to nanoseconds and `TimeAmount(.min)` if it underflows. @inlinable public static func hours(_ amount: Int64) -> TimeAmount { TimeAmount(_cappedNanoseconds(amount: amount, multiplier: 1000 * 1000 * 1000 * 60 * 60)) @@ -527,8 +529,8 @@ public struct TimeAmount: Hashable, Sendable { /// Converts `amount` to nanoseconds multiplying it by `multiplier`. The return value is capped to `Int64.max` if the multiplication overflows and `Int64.min` if it underflows. /// /// - parameters: - /// - amount: the amount to be converted to nanoseconds. - /// - multiplier: the multiplier that converts the given amount to nanoseconds. + /// - amount: the amount to be converted to nanoseconds. + /// - multiplier: the multiplier that converts the given amount to nanoseconds. /// - returns: the amount converted to nanoseconds within [Int64.min, Int64.max]. @inlinable static func _cappedNanoseconds(amount: Int64, multiplier: Int64) -> Int64 { @@ -602,7 +604,7 @@ extension TimeAmount: AdditiveArithmetic { /// doSomething(deadline: .now() + .seconds(5)) /// ``` /// -/// - note: `NIODeadline` should not be used to represent a time interval +/// - Note: `NIODeadline` should not be used to represent a time interval public struct NIODeadline: Equatable, Hashable, Sendable { @available(*, deprecated, message: "This typealias doesn't serve any purpose, please use UInt64 directly.") public typealias Value = UInt64 @@ -746,9 +748,9 @@ extension EventLoop { /// The returned `EventLoopFuture` will be completed when `task` has finished running. It will be succeeded with /// `task`'s return value or failed if the execution of `task` threw an error. /// - /// - parameters: - /// - task: The synchronous task to run. As everything that runs on the `EventLoop`, it must not block. - /// - returns: An `EventLoopFuture` containing the result of `task`'s execution. + /// - Parameters: + /// - task: The synchronous task to run. As everything that runs on the `EventLoop`, it must not block. + /// - Returns: An `EventLoopFuture` containing the result of `task`'s execution. @inlinable @preconcurrency public func submit(_ task: @escaping @Sendable () throws -> T) -> EventLoopFuture { @@ -770,9 +772,9 @@ extension EventLoop { /// The returned `EventLoopFuture` will be completed when `task` has finished running. It will be identical to /// the `EventLoopFuture` returned by `task`. /// - /// - parameters: - /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: An `EventLoopFuture` identical to the `EventLoopFuture` returned from `task`. + /// - Parameters: + /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: An `EventLoopFuture` identical to the `EventLoopFuture` returned from `task`. @inlinable @preconcurrency public func flatSubmit(_ task: @escaping @Sendable () -> EventLoopFuture) -> EventLoopFuture { @@ -784,12 +786,15 @@ extension EventLoop { /// - Note: The `T` must be `Sendable` since the isolation domains of the event loop future returned from `task` and /// this event loop might differ. /// - /// - parameters: - /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - deadline: The instant in time before which the task will not execute. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the full execution of the task, including its returned `EventLoopFuture`. /// - /// - note: You can only cancel a task before it has started executing. + /// - Note: You can only cancel a task before it has started executing. @discardableResult @inlinable @preconcurrency @@ -811,12 +816,15 @@ extension EventLoop { /// - Note: The `T` must be `Sendable` since the isolation domains of the event loop future returned from `task` and /// this event loop might differ. /// - /// - parameters: - /// - task: The asynchronous task to run. As everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - delay: The amount of time before which the task will not execute. + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. + /// - task: The asynchronous task to run. As everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the full execution of the task, including its returned `EventLoopFuture`. /// - /// - note: You can only cancel a task before it has started executing. + /// - Note: You can only cancel a task before it has started executing. @discardableResult @inlinable @preconcurrency @@ -857,9 +865,9 @@ extension EventLoop { /// Creates and returns a new `EventLoopFuture` that is already marked as failed. Notifications will be done using this `EventLoop` as execution `NIOThread`. /// - /// - parameters: - /// - error: the `Error` that is used by the `EventLoopFuture`. - /// - returns: a failed `EventLoopFuture`. + /// - Parameters: + /// - error: the `Error` that is used by the `EventLoopFuture`. + /// - Returns: a failed `EventLoopFuture`. @inlinable public func makeFailedFuture(_ error: Error) -> EventLoopFuture { EventLoopFuture(eventLoop: self, error: error) @@ -867,9 +875,9 @@ extension EventLoop { /// Creates and returns a new `EventLoopFuture` that is already marked as success. Notifications will be done using this `EventLoop` as execution `NIOThread`. /// - /// - parameters: - /// - result: the value that is used by the `EventLoopFuture`. - /// - returns: a succeeded `EventLoopFuture`. + /// - Parameters: + /// - value: the value that is used by the `EventLoopFuture`. + /// - Returns: a succeeded `EventLoopFuture`. @preconcurrency @inlinable public func makeSucceededFuture(_ value: Success) -> EventLoopFuture { @@ -913,14 +921,14 @@ extension EventLoop { /// An `EventLoop` forms a singular `EventLoopGroup`, returning itself as the 'next' `EventLoop`. /// - /// - returns: Itself, because an `EventLoop` forms a singular `EventLoopGroup`. + /// - Returns: Itself, because an `EventLoop` forms a singular `EventLoopGroup`. public func next() -> EventLoop { self } /// An `EventLoop` forms a singular `EventLoopGroup`, returning itself as 'any' `EventLoop`. /// - /// - returns: Itself, because an `EventLoop` forms a singular `EventLoopGroup`. + /// - Returns: Itself, because an `EventLoop` forms a singular `EventLoopGroup`. public func any() -> EventLoop { self } @@ -933,11 +941,11 @@ extension EventLoop { /// Schedule a repeated task to be executed by the `EventLoop` with a fixed delay between the end and start of each /// task. /// - /// - parameters: - /// - initialDelay: The delay after which the first task is executed. - /// - delay: The delay between the end of one task and the start of the next. - /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. - /// - task: The closure that will be executed. + /// - Parameters: + /// - initialDelay: The delay after which the first task is executed. + /// - delay: The delay between the end of one task and the start of the next. + /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. + /// - task: The closure that will be executed. /// - return: `RepeatedTask` @discardableResult @preconcurrency @@ -953,12 +961,12 @@ extension EventLoop { /// Schedule a repeated task to be executed by the `EventLoop` with a fixed delay between the end and start of each /// task. /// - /// - parameters: - /// - initialDelay: The delay after which the first task is executed. - /// - delay: The delay between the end of one task and the start of the next. - /// - maximumAllowableJitter: Exclusive upper bound of jitter range added to the `delay` parameter. - /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. - /// - task: The closure that will be executed. + /// - Parameters: + /// - initialDelay: The delay after which the first task is executed. + /// - delay: The delay between the end of one task and the start of the next. + /// - maximumAllowableJitter: Exclusive upper bound of jitter range added to the `delay` parameter. + /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. + /// - task: The closure that will be executed. /// - return: `RepeatedTask` @discardableResult public func scheduleRepeatedTask( @@ -1002,16 +1010,16 @@ extension EventLoop { /// Schedule a repeated asynchronous task to be executed by the `EventLoop` with a fixed delay between the end and /// start of each task. /// - /// - note: The delay is measured from the completion of one run's returned future to the start of the execution of + /// - Note: The delay is measured from the completion of one run's returned future to the start of the execution of /// the next run. For example: If you schedule a task once per second but your task takes two seconds to /// complete, the time interval between two subsequent runs will actually be three seconds (2s run time plus /// the 1s delay.) /// - /// - parameters: - /// - initialDelay: The delay after which the first task is executed. - /// - delay: The delay between the end of one task and the start of the next. - /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. - /// - task: The closure that will be executed. Task will keep repeating regardless of whether the future + /// - Parameters: + /// - initialDelay: The delay after which the first task is executed. + /// - delay: The delay between the end of one task and the start of the next. + /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. + /// - task: The closure that will be executed. Task will keep repeating regardless of whether the future /// gets fulfilled with success or error. /// /// - return: `RepeatedTask` @@ -1029,17 +1037,17 @@ extension EventLoop { /// Schedule a repeated asynchronous task to be executed by the `EventLoop` with a fixed delay between the end and /// start of each task. /// - /// - note: The delay is measured from the completion of one run's returned future to the start of the execution of + /// - Note: The delay is measured from the completion of one run's returned future to the start of the execution of /// the next run. For example: If you schedule a task once per second but your task takes two seconds to /// complete, the time interval between two subsequent runs will actually be three seconds (2s run time plus /// the 1s delay.) /// - /// - parameters: - /// - initialDelay: The delay after which the first task is executed. - /// - delay: The delay between the end of one task and the start of the next. - /// - maximumAllowableJitter: Exclusive upper bound of jitter range added to the `delay` parameter. - /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. - /// - task: The closure that will be executed. Task will keep repeating regardless of whether the future + /// - Parameters: + /// - initialDelay: The delay after which the first task is executed. + /// - delay: The delay between the end of one task and the start of the next. + /// - maximumAllowableJitter: Exclusive upper bound of jitter range added to the `delay` parameter. + /// - promise: If non-nil, a promise to fulfill when the task is cancelled and all execution is complete. + /// - task: The closure that will be executed. Task will keep repeating regardless of whether the future /// gets fulfilled with success or error. /// /// - return: `RepeatedTask` @@ -1078,10 +1086,10 @@ extension EventLoop { /// Adds a random amount of `.nanoseconds` (within `.zero.. EventLoopIterator { EventLoopIterator([self]) } @@ -1102,7 +1110,7 @@ extension EventLoop { /// Otherwise, if running in debug mode, the process will be abnormally terminated as per the semantics of /// `preconditionFailure(_:file:line:)`. Never has any effect in release mode. /// - /// - note: This is not a customization point so calls to this function can be fully optimized out in release mode. + /// - Note: This is not a customization point so calls to this function can be fully optimized out in release mode. @inlinable public func assertInEventLoop(file: StaticString = #fileID, line: UInt = #line) { debugOnly { @@ -1114,7 +1122,7 @@ extension EventLoop { /// Otherwise, if running in debug mode, the process will be abnormally terminated as per the semantics of /// `preconditionFailure(_:file:line:)`. Never has any effect in release mode. /// - /// - note: This is not a customization point so calls to this function can be fully optimized out in release mode. + /// - Note: This is not a customization point so calls to this function can be fully optimized out in release mode. @inlinable public func assertNotInEventLoop(file: StaticString = #fileID, line: UInt = #line) { debugOnly { @@ -1158,7 +1166,7 @@ public protocol EventLoopGroup: AnyObject, _NIOPreconcurrencySendable { /// choosing the current one. Use this method only if you are truly happy with _any_ `EventLoop` of this /// `EventLoopGroup` instance. /// - /// - note: You will only receive the current `EventLoop` here iff the current `EventLoop` belongs to the + /// - Note: You will only receive the current `EventLoop` here iff the current `EventLoop` belongs to the /// `EventLoopGroup` you call `any()` on. /// /// This method is useful having access to an `EventLoopGroup` without the knowledge of which `EventLoop` would be @@ -1183,7 +1191,7 @@ public protocol EventLoopGroup: AnyObject, _NIOPreconcurrencySendable { /// Returns an `EventLoopIterator` over the `EventLoop`s in this `EventLoopGroup`. /// - /// - returns: `EventLoopIterator` + /// - Returns: `EventLoopIterator` func makeIterator() -> EventLoopIterator /// Must crash if it's not safe to call `syncShutdownGracefully` in the current context. diff --git a/Sources/NIOCore/EventLoopFuture+AssumeIsolated.swift b/Sources/NIOCore/EventLoopFuture+AssumeIsolated.swift index bd7df99c56..d2dded2cfd 100644 --- a/Sources/NIOCore/EventLoopFuture+AssumeIsolated.swift +++ b/Sources/NIOCore/EventLoopFuture+AssumeIsolated.swift @@ -36,9 +36,9 @@ struct IsolatedEventLoop { /// Submit a given task to be executed by the `EventLoop`. Once the execution is complete the returned `EventLoopFuture` is notified. /// - /// - parameters: - /// - task: The closure that will be submitted to the `EventLoop` for execution. - /// - returns: `EventLoopFuture` that is notified once the task was executed. + /// - Parameters: + /// - task: The closure that will be submitted to the `EventLoop` for execution. + /// - Returns: `EventLoopFuture` that is notified once the task was executed. @inlinable func submit(_ task: @escaping () throws -> T) -> EventLoopFuture { self._wrapped.assertInEventLoop() @@ -50,12 +50,12 @@ struct IsolatedEventLoop { /// Schedule a `task` that is executed by this `EventLoop` at the given time. /// - /// - parameters: - /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the completion of the task. /// - /// - note: You can only cancel a task before it has started executing. + /// - Note: You can only cancel a task before it has started executing. @discardableResult @inlinable func scheduleTask( @@ -71,13 +71,13 @@ struct IsolatedEventLoop { /// Schedule a `task` that is executed by this `EventLoop` after the given amount of time. /// - /// - parameters: - /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - task: The synchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the completion of the task. /// - /// - note: You can only cancel a task before it has started executing. - /// - note: The `in` value is clamped to a maximum when running on a Darwin-kernel. + /// - Note: You can only cancel a task before it has started executing. + /// - Note: The `in` value is clamped to a maximum when running on a Darwin-kernel. @discardableResult @inlinable func scheduleTask( @@ -96,12 +96,12 @@ struct IsolatedEventLoop { /// - Note: The `T` must be `Sendable` since the isolation domains of the event loop future returned from `task` and /// this event loop might differ. /// - /// - parameters: - /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. - /// - returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait + /// - Parameters: + /// - task: The asynchronous task to run. As with everything that runs on the `EventLoop`, it must not block. + /// - Returns: A `Scheduled` object which may be used to cancel the task if it has not yet run, or to wait /// on the full execution of the task, including its returned `EventLoopFuture`. /// - /// - note: You can only cancel a task before it has started executing. + /// - Note: You can only cancel a task before it has started executing. @discardableResult @inlinable func flatScheduleTask( @@ -162,10 +162,10 @@ extension EventLoopFuture { /// /// Note: In a sense, the `EventLoopFuture` is returned before it's created. /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable func flatMap( _ callback: @escaping (Value) -> EventLoopFuture @@ -187,10 +187,10 @@ extension EventLoopFuture { /// /// If your callback function throws, the returned `EventLoopFuture` will error. /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable func flatMapThrowing( _ callback: @escaping (Value) throws -> NewValue @@ -212,10 +212,10 @@ extension EventLoopFuture { /// /// If your callback function throws, the returned `EventLoopFuture` will error. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value or a rethrown error. + /// - Returns: A future that will receive the eventual value or a rethrown error. @inlinable func flatMapErrorThrowing( _ callback: @escaping (Error) throws -> Value @@ -249,10 +249,10 @@ extension EventLoopFuture { /// } /// ``` /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable func map( _ callback: @escaping (Value) -> (NewValue) @@ -274,10 +274,10 @@ extension EventLoopFuture { /// - Note: The `Value` must be `Sendable` since the isolation domains of this future and the future returned from the callback /// might differ i.e. they might be bound to different event loops. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the recovered value. + /// - Returns: A future that will receive the recovered value. @inlinable func flatMapError( _ callback: @escaping (Error) -> EventLoopFuture @@ -298,10 +298,10 @@ extension EventLoopFuture { /// performs a simple data transformation that can potentially error. /// /// - /// - parameters: - /// - body: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - body: Function that will receive the value of this `EventLoopFuture` and return /// a new value or error lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable func flatMapResult( _ body: @escaping (Value) -> Result @@ -321,10 +321,10 @@ extension EventLoopFuture { /// event loop. `recover` is intended for use when you have the ability to synchronously /// recover from errors. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the recovered value. + /// - Returns: A future that will receive the recovered value. @inlinable func recover( _ callback: @escaping (Error) -> Value @@ -344,8 +344,8 @@ extension EventLoopFuture { /// If you find yourself passing the results from this `EventLoopFuture` to a new `EventLoopPromise` /// in the body of this function, consider using `cascade` instead. /// - /// - parameters: - /// - callback: The callback that is called with the successful result of the `EventLoopFuture`. + /// - Parameters: + /// - callback: The callback that is called with the successful result of the `EventLoopFuture`. @inlinable func whenSuccess(_ callback: @escaping (Value) -> Void) { self._wrapped.eventLoop.assertInEventLoop() @@ -363,8 +363,8 @@ extension EventLoopFuture { /// If you find yourself passing the results from this `EventLoopFuture` to a new `EventLoopPromise` /// in the body of this function, consider using `cascade` instead. /// - /// - parameters: - /// - callback: The callback that is called with the failed result of the `EventLoopFuture`. + /// - Parameters: + /// - callback: The callback that is called with the failed result of the `EventLoopFuture`. @inlinable func whenFailure(_ callback: @escaping (Error) -> Void) { self._wrapped.eventLoop.assertInEventLoop() @@ -377,8 +377,8 @@ extension EventLoopFuture { /// Adds an observer callback to this `EventLoopFuture` that is called when the /// `EventLoopFuture` has any result. /// - /// - parameters: - /// - callback: The callback that is called when the `EventLoopFuture` is fulfilled. + /// - Parameters: + /// - callback: The callback that is called when the `EventLoopFuture` is fulfilled. @inlinable func whenComplete( _ callback: @escaping (Result) -> Void @@ -393,9 +393,9 @@ extension EventLoopFuture { /// Adds an observer callback to this `EventLoopFuture` that is called when the /// `EventLoopFuture` has any result. /// - /// - parameters: - /// - callback: the callback that is called when the `EventLoopFuture` is fulfilled. - /// - returns: the current `EventLoopFuture` + /// - Parameters: + /// - callback: the callback that is called when the `EventLoopFuture` is fulfilled. + /// - Returns: the current `EventLoopFuture` @inlinable func always( _ callback: @escaping (Result) -> Void @@ -415,9 +415,9 @@ extension EventLoopFuture { /// promise.futureResult.unwrap(orReplace: 42).wait() /// ``` /// - /// - parameters: - /// - orReplace: the value of the returned `EventLoopFuture` when then resolved future's value is `Optional.some()`. - /// - returns: an new `EventLoopFuture` with new type parameter `NewValue` and the value passed in the `orReplace` parameter. + /// - Parameters: + /// - orReplace: the value of the returned `EventLoopFuture` when then resolved future's value is `Optional.some()`. + /// - Returns: an new `EventLoopFuture` with new type parameter `NewValue` and the value passed in the `orReplace` parameter. @inlinable func unwrap( orReplace replacement: NewValue @@ -439,10 +439,10 @@ extension EventLoopFuture { /// promise.futureResult.unwrap(orElse: { x * 2 }).wait() /// ``` /// - /// - parameters: - /// - orElse: a closure that returns the value of the returned `EventLoopFuture` when then resolved future's value + /// - Parameters: + /// - orElse: a closure that returns the value of the returned `EventLoopFuture` when then resolved future's value /// is `Optional.some()`. - /// - returns: an new `EventLoopFuture` with new type parameter `NewValue` and with the value returned by the closure + /// - Returns: an new `EventLoopFuture` with new type parameter `NewValue` and with the value returned by the closure /// passed in the `orElse` parameter. @inlinable func unwrap( @@ -481,8 +481,8 @@ extension EventLoopPromise { /// Deliver a successful result to the associated `EventLoopFuture` object. /// - /// - parameters: - /// - value: The successful result of the operation. + /// - Parameters: + /// - value: The successful result of the operation. @inlinable func succeed(_ value: Value) { self._wrapped.futureResult.eventLoop.assertInEventLoop() @@ -501,8 +501,8 @@ extension EventLoopPromise { /// } /// ``` /// - /// - parameters: - /// - result: The result which will be used to succeed or fail this promise. + /// - Parameters: + /// - result: The result which will be used to succeed or fail this promise. @inlinable func completeWith(_ result: Result) { self._wrapped.futureResult.eventLoop.assertInEventLoop() diff --git a/Sources/NIOCore/EventLoopFuture+WithEventLoop.swift b/Sources/NIOCore/EventLoopFuture+WithEventLoop.swift index 48e2b526f6..60ecc44687 100644 --- a/Sources/NIOCore/EventLoopFuture+WithEventLoop.swift +++ b/Sources/NIOCore/EventLoopFuture+WithEventLoop.swift @@ -35,10 +35,10 @@ extension EventLoopFuture { /// /// Note: In a sense, the `EventLoopFuture` is returned before it's created. /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable @preconcurrency public func flatMapWithEventLoop( @@ -71,10 +71,10 @@ extension EventLoopFuture { /// /// If the callback cannot recover it should return a failed `EventLoopFuture`. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the recovered value. + /// - Returns: A future that will receive the recovered value. @inlinable @preconcurrency public func flatMapErrorWithEventLoop( @@ -112,10 +112,10 @@ extension EventLoopFuture { /// `EventLoopFuture` objects will no longer be waited for. This function therefore fails fast: once /// a failure is encountered, it will immediately fail the overall EventLoopFuture. /// - /// - parameters: - /// - futures: An array of `EventLoopFuture` to wait for. - /// - with: A function that will be used to fold the values of two `EventLoopFuture`s and return a new value wrapped in an `EventLoopFuture`. - /// - returns: A new `EventLoopFuture` with the folded value whose callbacks run on `self.eventLoop`. + /// - Parameters: + /// - futures: An array of `EventLoopFuture` to wait for. + /// - combiningFunction: A function that will be used to fold the values of two `EventLoopFuture`s and return a new value wrapped in an `EventLoopFuture`. + /// - Returns: A new `EventLoopFuture` with the folded value whose callbacks run on `self.eventLoop`. @inlinable @preconcurrency public func foldWithEventLoop( diff --git a/Sources/NIOCore/EventLoopFuture.swift b/Sources/NIOCore/EventLoopFuture.swift index d72fe23c33..ea5632e5c1 100644 --- a/Sources/NIOCore/EventLoopFuture.swift +++ b/Sources/NIOCore/EventLoopFuture.swift @@ -153,7 +153,7 @@ internal struct OperationPlaceholderError: Error { /// some other API, create an already-resolved object with `eventLoop.makeSucceededFuture(result)` /// or `eventLoop.newFailedFuture(error:)`. /// -/// - note: `EventLoopPromise` has reference semantics. +/// - Note: `EventLoopPromise` has reference semantics. public struct EventLoopPromise { /// The `EventLoopFuture` which is used by the `EventLoopPromise`. You can use it to add callbacks which are notified once the /// `EventLoopPromise` is completed. @@ -170,10 +170,10 @@ public struct EventLoopPromise { /// General initializer /// - /// - parameters: - /// - eventLoop: The event loop this promise is tied to. - /// - file: The file this promise was allocated in, for debugging purposes. - /// - line: The line this promise was allocated on, for debugging purposes. + /// - Parameters: + /// - eventLoop: The event loop this promise is tied to. + /// - file: The file this promise was allocated in, for debugging purposes. + /// - line: The line this promise was allocated on, for debugging purposes. @inlinable internal init(eventLoop: EventLoop, file: StaticString, line: UInt) { self.futureResult = EventLoopFuture(_eventLoop: eventLoop, file: file, line: line) @@ -181,8 +181,8 @@ public struct EventLoopPromise { /// Deliver a successful result to the associated `EventLoopFuture` object. /// - /// - parameters: - /// - value: The successful result of the operation. + /// - Parameters: + /// - value: The successful result of the operation. @preconcurrency @inlinable public func succeed(_ value: Value) where Value: Sendable { @@ -191,7 +191,7 @@ public struct EventLoopPromise { /// Deliver an error to the associated `EventLoopFuture` object. /// - /// - parameters: + /// - Parameters: /// - error: The error from the operation. @inlinable public func fail(_ error: Error) { @@ -212,8 +212,8 @@ public struct EventLoopPromise { /// - Note: The `Value` must be `Sendable` since the isolation domains of the passed future and this promise might differ i.e. /// they might be bound to different event loops. /// - /// - parameters: - /// - future: The future whose value will be used to succeed or fail this promise. + /// - Parameters: + /// - future: The future whose value will be used to succeed or fail this promise. /// - seealso: `EventLoopFuture.cascade(to:)` @preconcurrency @inlinable @@ -233,8 +233,8 @@ public struct EventLoopPromise { /// } /// ``` /// - /// - parameters: - /// - result: The result which will be used to succeed or fail this promise. + /// - Parameters: + /// - result: The result which will be used to succeed or fail this promise. @preconcurrency @inlinable public func completeWith(_ result: Result) where Value: Sendable { @@ -247,8 +247,8 @@ public struct EventLoopPromise { /// other `Promise` implementations: specifically, all callbacks fire on the `EventLoop` /// that was used to create the promise. /// - /// - parameters: - /// - value: The value to fire the future with. + /// - Parameters: + /// - value: The value to fire the future with. @inlinable internal func _resolve(value: Result) where Value: Sendable { if self.futureResult.eventLoop.inEventLoop { @@ -262,9 +262,9 @@ public struct EventLoopPromise { /// Set the future result and get the associated callbacks. /// - /// - parameters: - /// - value: The result of the promise. - /// - returns: The callback list to run. + /// - Parameters: + /// - value: The result of the promise. + /// - Returns: The callback list to run. @inlinable internal func _setValue(value: Result) -> CallbackList { self.futureResult._setValue(value: value) @@ -486,10 +486,10 @@ extension EventLoopFuture { /// - Note: The `NewValue` must be `Sendable` since the isolation domains of this future and the future returned from the callback /// might differ i.e. they might be bound to different event loops. /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable @preconcurrency public func flatMap( @@ -534,10 +534,10 @@ extension EventLoopFuture { /// - Note: The `NewValue` must be `Sendable` since the isolation domains of this future and the future returned from the callback /// might differ i.e. they might be bound to different event loops. /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable @preconcurrency public func flatMapThrowing( @@ -578,10 +578,10 @@ extension EventLoopFuture { /// /// If your callback function throws, the returned `EventLoopFuture` will error. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value or a rethrown error. + /// - Returns: A future that will receive the eventual value or a rethrown error. @inlinable @preconcurrency public func flatMapErrorThrowing( @@ -632,10 +632,10 @@ extension EventLoopFuture { /// } /// ``` /// - /// - parameters: - /// - callback: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable @preconcurrency public func map( @@ -671,10 +671,10 @@ extension EventLoopFuture { /// - Note: The `Value` must be `Sendable` since the isolation domains of this future and the future returned from the callback /// might differ i.e. they might be bound to different event loops. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the recovered value. + /// - Returns: A future that will receive the recovered value. @inlinable @preconcurrency public func flatMapError( @@ -709,10 +709,10 @@ extension EventLoopFuture { /// performs a simple data transformation that can potentially error. /// /// - /// - parameters: - /// - body: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - body: Function that will receive the value of this `EventLoopFuture` and return /// a new value or error lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the eventual value. + /// - Returns: A future that will receive the eventual value. @inlinable @preconcurrency public func flatMapResult( @@ -753,10 +753,10 @@ extension EventLoopFuture { /// event loop. `recover` is intended for use when you have the ability to synchronously /// recover from errors. /// - /// - parameters: - /// - callback: Function that will receive the error value of this `EventLoopFuture` and return + /// - Parameters: + /// - callback: Function that will receive the error value of this `EventLoopFuture` and return /// a new value lifted into a new `EventLoopFuture`. - /// - returns: A future that will receive the recovered value. + /// - Returns: A future that will receive the recovered value. @inlinable @preconcurrency public func recover(_ callback: @escaping @Sendable (Error) -> Value) -> EventLoopFuture { @@ -811,8 +811,8 @@ extension EventLoopFuture { /// If you find yourself passing the results from this `EventLoopFuture` to a new `EventLoopPromise` /// in the body of this function, consider using `cascade` instead. /// - /// - parameters: - /// - callback: The callback that is called with the successful result of the `EventLoopFuture`. + /// - Parameters: + /// - callback: The callback that is called with the successful result of the `EventLoopFuture`. @inlinable @preconcurrency public func whenSuccess(_ callback: @escaping @Sendable (Value) -> Void) { @@ -832,8 +832,8 @@ extension EventLoopFuture { /// If you find yourself passing the results from this `EventLoopFuture` to a new `EventLoopPromise` /// in the body of this function, consider using `cascade` instead. /// - /// - parameters: - /// - callback: The callback that is called with the failed result of the `EventLoopFuture`. + /// - Parameters: + /// - callback: The callback that is called with the failed result of the `EventLoopFuture`. @inlinable @preconcurrency public func whenFailure(_ callback: @escaping @Sendable (Error) -> Void) { @@ -848,8 +848,8 @@ extension EventLoopFuture { /// Adds an observer callback to this `EventLoopFuture` that is called when the /// `EventLoopFuture` has any result. /// - /// - parameters: - /// - callback: The callback that is called when the `EventLoopFuture` is fulfilled. + /// - Parameters: + /// - callback: The callback that is called when the `EventLoopFuture` is fulfilled. @inlinable @preconcurrency public func whenComplete(_ callback: @escaping @Sendable (Result) -> Void) { @@ -976,7 +976,7 @@ extension EventLoopFuture { /// - Note: The `Value` must be `Sendable` since the isolation domains of this future and the promise might differ i.e. /// they might be bound to different event loops. /// - /// - Parameter to: The `EventLoopPromise` to fulfill with the results of this future. + /// - Parameter promise: The `EventLoopPromise` to fulfill with the results of this future. /// - SeeAlso: `EventLoopPromise.completeWith(_:)` @preconcurrency @inlinable @@ -1004,7 +1004,7 @@ extension EventLoopFuture { /// - Note: The `Value` must be `Sendable` since the isolation domains of this future and the promise might differ i.e. /// they might be bound to different event loops. /// - /// - Parameter to: The `EventLoopPromise` to fulfill when a successful result is available. + /// - Parameter promise: The `EventLoopPromise` to fulfill when a successful result is available. @preconcurrency @inlinable public func cascadeSuccess(to promise: EventLoopPromise?) where Value: Sendable { @@ -1018,7 +1018,7 @@ extension EventLoopFuture { /// error cases, while passing the user `EventLoopPromise` onwards. /// /// - /// - Parameter to: The `EventLoopPromise` that should fail with the error of this `EventLoopFuture`. + /// - Parameter promise: The `EventLoopPromise` that should fail with the error of this `EventLoopFuture`. @inlinable public func cascadeFailure(to promise: EventLoopPromise?) { guard let promise = promise else { return } @@ -1042,8 +1042,8 @@ extension EventLoopFuture { /// /// - Note: The `Value` must be `Sendable` since it is shared outside of the isolation domain of the event loop. /// - /// - returns: The value of the `EventLoopFuture` when it completes. - /// - throws: The error value of the `EventLoopFuture` if it errors. + /// - Returns: The value of the `EventLoopFuture` when it completes. + /// - Throws: The error value of the `EventLoopFuture` if it errors. @available(*, noasync, message: "wait() can block indefinitely, prefer get()", renamed: "get()") @preconcurrency @inlinable @@ -1093,10 +1093,10 @@ extension EventLoopFuture { /// - Note: The `Value` and `NewValue` must be `Sendable` since the isolation domains of this future and the other futures might differ i.e. /// they might be bound to different event loops. /// - /// - parameters: - /// - futures: An array of `EventLoopFuture` to wait for. - /// - with: A function that will be used to fold the values of two `EventLoopFuture`s and return a new value wrapped in an `EventLoopFuture`. - /// - returns: A new `EventLoopFuture` with the folded value whose callbacks run on `self.eventLoop`. + /// - Parameters: + /// - futures: An array of `EventLoopFuture` to wait for. + /// - combiningFunction: A function that will be used to fold the values of two `EventLoopFuture`s and return a new value wrapped in an `EventLoopFuture`. + /// - Returns: A new `EventLoopFuture` with the folded value whose callbacks run on `self.eventLoop`. @inlinable @preconcurrency public func fold( @@ -1149,12 +1149,12 @@ extension EventLoopFuture { /// - Note: The `Value` and `InputValue` must be `Sendable` since the isolation domains of this future and the other futures might differ i.e. /// they might be bound to different event loops. /// - /// - parameters: - /// - initialResult: An initial result to begin the reduction. - /// - futures: An array of `EventLoopFuture` to wait for. - /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. - /// - nextPartialResult: The bifunction used to produce partial results. - /// - returns: A new `EventLoopFuture` with the reduced value. + /// - Parameters: + /// - initialResult: An initial result to begin the reduction. + /// - futures: An array of `EventLoopFuture` to wait for. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. + /// - nextPartialResult: The bifunction used to produce partial results. + /// - Returns: A new `EventLoopFuture` with the reduced value. @preconcurrency @inlinable public static func reduce( @@ -1197,12 +1197,12 @@ extension EventLoopFuture { /// - Note: The `Value` and `InputValue` must be `Sendable` since the isolation domains of this future and the other futures might differ i.e. /// they might be bound to different event loops. /// - /// - parameters: - /// - initialResult: An initial result to begin the reduction. - /// - futures: An array of `EventLoopFuture` to wait for. - /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. - /// - updateAccumulatingResult: The bifunction used to combine partialResults with new elements. - /// - returns: A new `EventLoopFuture` with the combined value. + /// - Parameters: + /// - initialResult: An initial result to begin the reduction. + /// - futures: An array of `EventLoopFuture` to wait for. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. + /// - updateAccumulatingResult: The bifunction used to combine partialResults with new elements. + /// - Returns: A new `EventLoopFuture` with the combined value. @inlinable @preconcurrency public static func reduce( @@ -1246,8 +1246,8 @@ extension EventLoopFuture { /// /// If it is desired to always succeed, regardless of failures, use `andAllComplete` instead. /// - Parameters: - /// - futures: An array of homogenous `EventLoopFutures`s to wait for. - /// - on: The `EventLoop` on which the new `EventLoopFuture` callbacks will execute on. + /// - futures: An array of homogenous `EventLoopFutures`s to wait for. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will execute on. /// - Returns: A new `EventLoopFuture` that waits for the other futures to succeed. @inlinable public static func andAllSucceed( @@ -1265,8 +1265,8 @@ extension EventLoopFuture { /// If the results of all futures should be collected use `andAllComplete` instead. /// /// - Parameters: - /// - futures: An array of homogenous `EventLoopFutures`s to wait for. - /// - promise: The `EventLoopPromise` to complete with the result of this call. + /// - futures: An array of homogenous `EventLoopFutures`s to wait for. + /// - promise: The `EventLoopPromise` to complete with the result of this call. @inlinable public static func andAllSucceed( _ futures: [EventLoopFuture], @@ -1292,8 +1292,8 @@ extension EventLoopFuture { /// they might be bound to different event loops. /// /// - Parameters: - /// - futures: An array of homogenous `EventLoopFuture`s to wait on for fulfilled values. - /// - on: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. + /// - futures: An array of homogenous `EventLoopFuture`s to wait on for fulfilled values. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. /// - Returns: A new `EventLoopFuture` with all of the values fulfilled by the provided futures. @preconcurrency public static func whenAllSucceed( @@ -1314,8 +1314,8 @@ extension EventLoopFuture { /// they might be bound to different event loops. /// /// - Parameters: - /// - futures: An array of homogenous `EventLoopFutures`s to wait for. - /// - promise: The `EventLoopPromise` to complete with the result of this call. + /// - futures: An array of homogenous `EventLoopFutures`s to wait for. + /// - promise: The `EventLoopPromise` to complete with the result of this call. @preconcurrency public static func whenAllSucceed( _ futures: [EventLoopFuture], @@ -1481,8 +1481,8 @@ extension EventLoopFuture { /// /// If the results are needed, use `whenAllComplete` instead. /// - Parameters: - /// - futures: An array of homogenous `EventLoopFuture`s to wait for. - /// - on: The `EventLoop` on which the new `EventLoopFuture` callbacks will execute on. + /// - futures: An array of homogenous `EventLoopFuture`s to wait for. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will execute on. /// - Returns: A new `EventLoopFuture` that succeeds after all futures complete. @inlinable public static func andAllComplete( @@ -1501,8 +1501,8 @@ extension EventLoopFuture { /// If the results are required, use `whenAllComplete` instead. /// /// - Parameters: - /// - futures: An array of homogenous `EventLoopFuture`s to wait for. - /// - promise: The `EventLoopPromise` to succeed when all futures have completed. + /// - futures: An array of homogenous `EventLoopFuture`s to wait for. + /// - promise: The `EventLoopPromise` to succeed when all futures have completed. @inlinable public static func andAllComplete( _ futures: [EventLoopFuture], @@ -1530,8 +1530,8 @@ extension EventLoopFuture { /// If it is desired to flatten them into a single `EventLoopFuture` that fails on the first `EventLoopFuture` failure, /// use one of the `reduce` methods instead. /// - Parameters: - /// - futures: An array of homogenous `EventLoopFuture`s to gather results from. - /// - on: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. + /// - futures: An array of homogenous `EventLoopFuture`s to gather results from. + /// - eventLoop: The `EventLoop` on which the new `EventLoopFuture` callbacks will fire. /// - Returns: A new `EventLoopFuture` with all the results of the provided futures. @preconcurrency @inlinable @@ -1552,8 +1552,8 @@ extension EventLoopFuture { /// they might be bound to different event loops. /// /// - Parameters: - /// - futures: An array of homogenous `EventLoopFuture`s to gather results from. - /// - promise: The `EventLoopPromise` to complete with the result of the futures. + /// - futures: An array of homogenous `EventLoopFuture`s to gather results from. + /// - promise: The `EventLoopPromise` to complete with the result of the futures. @preconcurrency @inlinable public static func whenAllComplete( @@ -1715,9 +1715,9 @@ extension EventLoopFuture { /// /// - Note: The `Value` must be `Sendable` since it is shared with the isolation domain of the target event loop. /// - /// - parameters: - /// - to: The `EventLoop` that the returned `EventLoopFuture` will run on. - /// - returns: An `EventLoopFuture` whose callbacks run on `target` instead of the original loop. + /// - Parameters: + /// - target: The `EventLoop` that the returned `EventLoopFuture` will run on. + /// - Returns: An `EventLoopFuture` whose callbacks run on `target` instead of the original loop. @preconcurrency @inlinable public func hop(to target: EventLoop) -> EventLoopFuture where Value: Sendable { @@ -1737,9 +1737,9 @@ extension EventLoopFuture { /// Adds an observer callback to this `EventLoopFuture` that is called when the /// `EventLoopFuture` has any result. /// - /// - parameters: - /// - callback: the callback that is called when the `EventLoopFuture` is fulfilled. - /// - returns: the current `EventLoopFuture` + /// - Parameters: + /// - callback: the callback that is called when the `EventLoopFuture` is fulfilled. + /// - Returns: the current `EventLoopFuture` @inlinable @preconcurrency public func always(_ callback: @escaping @Sendable (Result) -> Void) -> EventLoopFuture { @@ -1764,16 +1764,16 @@ extension EventLoopFuture { /// } /// ``` /// - /// - parameters: - /// - orError: the `Error` that is thrown when then resolved future's value is `Optional.none`. - /// - returns: an new `EventLoopFuture` with new type parameter `NewValue` and the same value as the resolved + /// - Parameters: + /// - orError: the `Error` that is thrown when then resolved future's value is `Optional.none`. + /// - Returns: an new `EventLoopFuture` with new type parameter `NewValue` and the same value as the resolved /// future. - /// - throws: the `Error` passed in the `orError` parameter when the resolved future's value is `Optional.none`. + /// - Throws: the `Error` passed in the `orError` parameter when the resolved future's value is `Optional.none`. @inlinable - public func unwrap(orError error: Error) -> EventLoopFuture where Value == NewValue? { + public func unwrap(orError: Error) -> EventLoopFuture where Value == NewValue? { self.flatMapThrowing { (value) throws -> NewValue in guard let value = value else { - throw error + throw orError } return value } @@ -1787,9 +1787,9 @@ extension EventLoopFuture { /// promise.futureResult.unwrap(orReplace: 42).wait() /// ``` /// - /// - parameters: - /// - orReplace: the value of the returned `EventLoopFuture` when then resolved future's value is `Optional.some()`. - /// - returns: an new `EventLoopFuture` with new type parameter `NewValue` and the value passed in the `orReplace` parameter. + /// - Parameters: + /// - replacement: the value of the returned `EventLoopFuture` when then resolved future's value is `Optional.some()`. + /// - Returns: an new `EventLoopFuture` with new type parameter `NewValue` and the value passed in the `replacement` parameter. @preconcurrency @inlinable public func unwrap( @@ -1812,11 +1812,11 @@ extension EventLoopFuture { /// promise.futureResult.unwrap(orElse: { x * 2 }).wait() /// ``` /// - /// - parameters: - /// - orElse: a closure that returns the value of the returned `EventLoopFuture` when then resolved future's value + /// - Parameters: + /// - callback: a closure that returns the value of the returned `EventLoopFuture` when then resolved future's value /// is `Optional.some()`. - /// - returns: an new `EventLoopFuture` with new type parameter `NewValue` and with the value returned by the closure - /// passed in the `orElse` parameter. + /// - Returns: an new `EventLoopFuture` with new type parameter `NewValue` and with the value returned by the closure + /// passed in the `callback` parameter. @inlinable @preconcurrency public func unwrap( @@ -1851,9 +1851,9 @@ extension EventLoopFuture { /// /// - Note: The `Value` and `NewValue` must be `Sendable` since it is shared between the isolation region queue and the event loop. /// - /// - parameters: - /// - onto: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. - /// - callbackMayBlock: Function that will receive the value of this `EventLoopFuture` and return + /// - Parameters: + /// - queue: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. + /// - callbackMayBlock: Function that will receive the value of this `EventLoopFuture` and return /// a new `EventLoopFuture`. @inlinable @preconcurrency @@ -1876,9 +1876,9 @@ extension EventLoopFuture { /// /// - Note: The `NewValue` must be `Sendable` since it is shared between the isolation region queue and the event loop. /// - /// - parameters: - /// - onto: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. - /// - callbackMayBlock: The callback that is called with the successful result of the `EventLoopFuture`. + /// - Parameters: + /// - queue: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. + /// - callbackMayBlock: The callback that is called with the successful result of the `EventLoopFuture`. @preconcurrency @inlinable public func whenSuccessBlocking( @@ -1898,9 +1898,9 @@ extension EventLoopFuture { /// If you find yourself passing the results from this `EventLoopFuture` to a new `EventLoopPromise` /// in the body of this function, consider using `cascade` instead. /// - /// - parameters: - /// - onto: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. - /// - callbackMayBlock: The callback that is called with the failed result of the `EventLoopFuture`. + /// - Parameters: + /// - queue: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. + /// - callbackMayBlock: The callback that is called with the failed result of the `EventLoopFuture`. @inlinable @preconcurrency public func whenFailureBlocking( @@ -1923,9 +1923,9 @@ extension EventLoopFuture { /// /// - Note: The `NewValue` must be `Sendable` since it is shared between the isolation region queue and the event loop. /// - /// - parameters: - /// - onto: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. - /// - callbackMayBlock: The callback that is called when the `EventLoopFuture` is fulfilled. + /// - Parameters: + /// - queue: the `DispatchQueue` on which the blocking IO / task specified by `callbackMayBlock` is scheduled. + /// - callbackMayBlock: The callback that is called when the `EventLoopFuture` is fulfilled. @inlinable @preconcurrency public func whenCompleteBlocking( @@ -1947,9 +1947,9 @@ extension EventLoopFuture { /// If the original future fails, it triggers an assertion failure, causing a runtime error during development. /// The assertion failure will include the file and line of the calling site. /// - /// - parameters: - /// - file: The file this function was called in, for debugging purposes. - /// - line: The line this function was called on, for debugging purposes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @inlinable public func assertSuccess(file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { self.always { result in @@ -1966,9 +1966,9 @@ extension EventLoopFuture { /// If the original future succeeds, it triggers an assertion failure, causing a runtime error during development. /// The assertion failure will include the file and line of the calling site. /// - /// - parameters: - /// - file: The file this function was called in, for debugging purposes. - /// - line: The line this function was called on, for debugging purposes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @inlinable public func assertFailure(file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { self.always { result in @@ -1986,9 +1986,9 @@ extension EventLoopFuture { /// If the original future fails, it triggers a precondition failure, causing a runtime error during development. /// The precondition failure will include the file and line of the calling site. /// - /// - parameters: - /// - file: The file this function was called in, for debugging purposes. - /// - line: The line this function was called on, for debugging purposes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @inlinable public func preconditionSuccess(file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { self.always { result in @@ -2006,9 +2006,9 @@ extension EventLoopFuture { /// If the original future succeeds, it triggers a precondition failure, causing a runtime error during development. /// The precondition failure will include the file and line of the calling site. /// - /// - parameters: - /// - file: The file this function was called in, for debugging purposes. - /// - line: The line this function was called on, for debugging purposes. + /// - Parameters: + /// - file: The file this function was called in, for debugging purposes. + /// - line: The line this function was called on, for debugging purposes. @inlinable public func preconditionFailure(file: StaticString = #fileID, line: UInt = #line) -> EventLoopFuture { self.always { result in diff --git a/Sources/NIOCore/FileDescriptor.swift b/Sources/NIOCore/FileDescriptor.swift index b9d2c8997b..530cc7d794 100644 --- a/Sources/NIOCore/FileDescriptor.swift +++ b/Sources/NIOCore/FileDescriptor.swift @@ -20,9 +20,9 @@ public protocol FileDescriptor { /// The ownership of the file descriptor must not escape the `body` as it's completely managed by the /// implementation of the `FileDescriptor` protocol. /// - /// - parameters: - /// - body: The closure to execute if the `FileDescriptor` is still open. - /// - throws: If either the `FileDescriptor` was closed before or the closure throws by itself. + /// - Parameters: + /// - body: The closure to execute if the `FileDescriptor` is still open. + /// - Throws: If either the `FileDescriptor` was closed before or the closure throws by itself. func withUnsafeFileDescriptor(_ body: (CInt) throws -> T) throws -> T /// `true` if this `FileDescriptor` is open (which means it was not closed yet). diff --git a/Sources/NIOCore/FileHandle.swift b/Sources/NIOCore/FileHandle.swift index 82500b9fb7..733aec483e 100644 --- a/Sources/NIOCore/FileHandle.swift +++ b/Sources/NIOCore/FileHandle.swift @@ -39,7 +39,7 @@ public typealias NIOPOSIXFileMode = mode_t /// When creating a `NIOFileHandle` it takes ownership of the underlying file descriptor. When a `NIOFileHandle` is no longer /// needed you must `close` it or take back ownership of the file descriptor using `takeDescriptorOwnership`. /// -/// - note: One underlying file descriptor should usually be managed by one `NIOFileHandle` only. +/// - Note: One underlying file descriptor should usually be managed by one `NIOFileHandle` only. /// /// - warning: Failing to manage the lifetime of a `NIOFileHandle` correctly will result in undefined behaviour. /// @@ -68,7 +68,7 @@ public final class NIOFileHandle: FileDescriptor { /// /// - warning: The returned `NIOFileHandle` is not fully independent, the seek pointer is shared as documented by `dup(2)`. /// - /// - returns: A new `NIOFileHandle` with a fresh underlying file descriptor but shared seek pointer. + /// - Returns: A new `NIOFileHandle` with a fresh underlying file descriptor but shared seek pointer. public func duplicate() throws -> NIOFileHandle { try withUnsafeFileDescriptor { fd in NIOFileHandle(descriptor: try SystemCalls.dup(descriptor: fd)) @@ -81,7 +81,7 @@ public final class NIOFileHandle: FileDescriptor { /// /// After calling this, the `NIOFileHandle` cannot be used for anything else and all the operations will throw. /// - /// - returns: The underlying file descriptor, now owned by the caller. + /// - Returns: The underlying file descriptor, now owned by the caller. public func takeDescriptorOwnership() throws -> CInt { guard self.isOpen else { throw IOError(errnoCode: EBADF, reason: "can't close file (as it's not open anymore).") @@ -152,8 +152,8 @@ extension NIOFileHandle { /// Allows file creation when opening file for writing. File owner is set to the effective user ID of the process. /// - /// - parameters: - /// - posixMode: `file mode` applied when file is created. Default permissions are: read and write for fileowner, read for owners group and others. + /// - Parameters: + /// - posixMode: `file mode` applied when file is created. Default permissions are: read and write for fileowner, read for owners group and others. public static func allowFileCreation(posixMode: NIOPOSIXFileMode = defaultPermissions) -> Flags { #if os(WASI) let flags = CNIOWASI_O_CREAT() @@ -165,10 +165,10 @@ extension NIOFileHandle { /// Allows the specification of POSIX flags (e.g. `O_TRUNC`) and mode (e.g. `S_IWUSR`) /// - /// - parameters: - /// - flags: The POSIX open flags (the second parameter for `open(2)`). - /// - mode: The POSIX mode (the third parameter for `open(2)`). - /// - returns: A `NIOFileHandle.Mode` equivalent to the given POSIX flags and mode. + /// - Parameters: + /// - flags: The POSIX open flags (the second parameter for `open(2)`). + /// - mode: The POSIX mode (the third parameter for `open(2)`). + /// - Returns: A `NIOFileHandle.Mode` equivalent to the given POSIX flags and mode. public static func posix(flags: CInt, mode: NIOPOSIXFileMode) -> Flags { Flags(posixMode: mode, posixFlags: flags) } @@ -176,10 +176,10 @@ extension NIOFileHandle { /// Open a new `NIOFileHandle`. This operation is blocking. /// - /// - parameters: - /// - path: The path of the file to open. The ownership of the file descriptor is transferred to this `NIOFileHandle` and so it will be closed once `close` is called. - /// - mode: Access mode. Default mode is `.read`. - /// - flags: Additional POSIX flags. + /// - Parameters: + /// - path: The path of the file to open. The ownership of the file descriptor is transferred to this `NIOFileHandle` and so it will be closed once `close` is called. + /// - mode: Access mode. Default mode is `.read`. + /// - flags: Additional POSIX flags. public convenience init(path: String, mode: Mode = .read, flags: Flags = .default) throws { #if os(Windows) let fl = mode.posixFlags | flags.posixFlags | _O_NOINHERIT @@ -192,8 +192,8 @@ extension NIOFileHandle { /// Open a new `NIOFileHandle`. This operation is blocking. /// - /// - parameters: - /// - path: The path of the file to open. The ownership of the file descriptor is transferred to this `NIOFileHandle` and so it will be closed once `close` is called. + /// - Parameters: + /// - path: The path of the file to open. The ownership of the file descriptor is transferred to this `NIOFileHandle` and so it will be closed once `close` is called. public convenience init(path: String) throws { // This function is here because we had a function like this in NIO 2.0, and the one above doesn't quite match. Sadly we can't // really deprecate this either, because it'll be preferred to the one above in many cases. diff --git a/Sources/NIOCore/FileRegion.swift b/Sources/NIOCore/FileRegion.swift index 6464872932..fdeef77844 100644 --- a/Sources/NIOCore/FileRegion.swift +++ b/Sources/NIOCore/FileRegion.swift @@ -37,7 +37,7 @@ import WASILibc /// One important note, depending your `ChannelPipeline` setup it may not be possible to use a `FileRegion` as a `ChannelHandler` may /// need access to the bytes (in a `ByteBuffer`) to transform these. /// -/// - note: It is important to manually manage the lifetime of the `NIOFileHandle` used to create a `FileRegion`. +/// - Note: It is important to manually manage the lifetime of the `NIOFileHandle` used to create a `FileRegion`. /// - warning: `FileRegion` objects are not thread-safe and are mutable. They also cannot be fully thread-safe as they refer to a global underlying file descriptor. public struct FileRegion { @@ -64,10 +64,10 @@ public struct FileRegion { /// Create a new `FileRegion` from an open `NIOFileHandle`. /// - /// - parameters: - /// - fileHandle: the `NIOFileHandle` to use. - /// - readerIndex: the index (offset) on which the reading will start. - /// - endIndex: the index which represent the end of the readable portion. + /// - Parameters: + /// - fileHandle: the `NIOFileHandle` to use. + /// - readerIndex: the index (offset) on which the reading will start. + /// - endIndex: the index which represent the end of the readable portion. public init(fileHandle: NIOFileHandle, readerIndex: Int, endIndex: Int) { precondition(readerIndex <= endIndex, "readerIndex(\(readerIndex) must be <= endIndex(\(endIndex).") @@ -95,8 +95,8 @@ extension FileRegion: Sendable {} extension FileRegion { /// Create a new `FileRegion` forming a complete file. /// - /// - parameters: - /// - fileHandle: An open `NIOFileHandle` to the file. + /// - Parameters: + /// - fileHandle: An open `NIOFileHandle` to the file. public init(fileHandle: NIOFileHandle) throws { let eof = try fileHandle.withUnsafeFileDescriptor { (fd: CInt) throws -> off_t in let eof = try SystemCalls.lseek(descriptor: fd, offset: 0, whence: SEEK_END) diff --git a/Sources/NIOCore/GlobalSingletons.swift b/Sources/NIOCore/GlobalSingletons.swift index 50865e07b5..97c2fffee6 100644 --- a/Sources/NIOCore/GlobalSingletons.swift +++ b/Sources/NIOCore/GlobalSingletons.swift @@ -47,7 +47,7 @@ extension NIOSingletons { /// The thread count is ``System/coreCount`` unless the environment variable `NIO_SINGLETON_GROUP_LOOP_COUNT` /// is set or this value was set manually by the user. /// - /// - note: This value must be set _before_ any singletons are used and must only be set once. + /// - Note: This value must be set _before_ any singletons are used and must only be set once. public static var groupLoopCountSuggestion: Int { set { Self.userSetSingletonThreadCount(rawStorage: globalRawSuggestedLoopCount, userValue: newValue) @@ -67,7 +67,7 @@ extension NIOSingletons { /// The thread count is ``System/coreCount`` unless the environment variable /// `NIO_SINGLETON_BLOCKING_POOL_THREAD_COUNT` is set or this value was set manually by the user. /// - /// - note: This value must be set _before_ any singletons are used and must only be set once. + /// - Note: This value must be set _before_ any singletons are used and must only be set once. public static var blockingPoolThreadCountSuggestion: Int { set { Self.userSetSingletonThreadCount(rawStorage: globalRawSuggestedBlockingThreadCount, userValue: newValue) @@ -85,7 +85,7 @@ extension NIOSingletons { /// /// This value cannot be changed using an environment variable. /// - /// - note: This value must be set _before_ any singletons are used and must only be set once. + /// - Note: This value must be set _before_ any singletons are used and must only be set once. public static var singletonsEnabledSuggestion: Bool { get { let (exchanged, original) = globalRawSingletonsEnabled.compareExchange( diff --git a/Sources/NIOCore/IO.swift b/Sources/NIOCore/IO.swift index 3b8ef1ed26..b356bfd179 100644 --- a/Sources/NIOCore/IO.swift +++ b/Sources/NIOCore/IO.swift @@ -98,32 +98,32 @@ public struct IOError: Swift.Error { /// Creates a new `IOError`` /// - /// - parameters: - /// - errorCode: the `errno` that was set for the operation. - /// - reason: the actual reason (in an human-readable form). - public init(errnoCode code: CInt, reason: String) { - self.error = .errno(code) + /// - Parameters: + /// - errnoCode: the `errno` that was set for the operation. + /// - reason: the actual reason (in an human-readable form). + public init(errnoCode: CInt, reason: String) { + self.error = .errno(errnoCode) self.failureDescription = reason } /// Creates a new `IOError`` /// - /// - parameters: - /// - errorCode: the `errno` that was set for the operation. - /// - function: The function the error happened in, the human readable description will be generated automatically when needed. + /// - Parameters: + /// - errnoCode: the `errno` that was set for the operation. + /// - function: The function the error happened in, the human readable description will be generated automatically when needed. @available(*, deprecated, renamed: "init(errnoCode:reason:)") - public init(errnoCode code: CInt, function: StaticString) { - self.error = .errno(code) + public init(errnoCode: CInt, function: StaticString) { + self.error = .errno(errnoCode) self.failureDescription = "\(function)" } } /// Returns a reason to use when constructing a `IOError`. /// -/// - parameters: -/// - errorCode: the `errno` that was set for the operation. -/// - reason: what failed -/// - returns: the constructed reason. +/// - Parameters: +/// - errnoCode: the `errno` that was set for the operation. +/// - reason: what failed +/// - Returns: the constructed reason. private func reasonForError(errnoCode: CInt, reason: String) -> String { if let errorDescC = strerror(errnoCode) { return "\(reason): \(String(cString: errorDescC)) (errno: \(errnoCode))" diff --git a/Sources/NIOCore/MarkedCircularBuffer.swift b/Sources/NIOCore/MarkedCircularBuffer.swift index 1881c824cb..5ea965f19c 100644 --- a/Sources/NIOCore/MarkedCircularBuffer.swift +++ b/Sources/NIOCore/MarkedCircularBuffer.swift @@ -23,8 +23,8 @@ public struct MarkedCircularBuffer: CustomStringConvertible { /// Create a new instance. /// - /// - parameters: - /// - initialCapacity: The initial capacity of the internal storage. + /// - Parameters: + /// - initialCapacity: The initial capacity of the internal storage. @inlinable public init(initialCapacity: Int) { self._buffer = CircularBuffer(initialCapacity: initialCapacity) diff --git a/Sources/NIOCore/MulticastChannel.swift b/Sources/NIOCore/MulticastChannel.swift index 45b2a68802..75658a0915 100644 --- a/Sources/NIOCore/MulticastChannel.swift +++ b/Sources/NIOCore/MulticastChannel.swift @@ -15,13 +15,13 @@ /// A `MulticastChannel` is a `Channel` that supports IP multicast operations: that is, a channel that can join multicast /// groups. /// -/// - note: As with `Channel`, all operations on a `MulticastChannel` are thread-safe. +/// - Note: As with `Channel`, all operations on a `MulticastChannel` are thread-safe. public protocol MulticastChannel: Channel { /// Request that the `MulticastChannel` join the multicast group given by `group`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. func joinGroup(_ group: SocketAddress, promise: EventLoopPromise?) @@ -29,10 +29,10 @@ public protocol MulticastChannel: Channel { /// Request that the `MulticastChannel` join the multicast group given by `group` on the interface /// given by `interface`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - interface: The interface on which to join the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - interface: The interface on which to join the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. @available(*, deprecated, renamed: "joinGroup(_:device:promise:)") func joinGroup(_ group: SocketAddress, interface: NIONetworkInterface?, promise: EventLoopPromise?) @@ -41,18 +41,18 @@ public protocol MulticastChannel: Channel { /// Request that the `MulticastChannel` join the multicast group given by `group` on the device /// given by `device`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - device: The device on which to join the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - device: The device on which to join the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. func joinGroup(_ group: SocketAddress, device: NIONetworkDevice?, promise: EventLoopPromise?) /// Request that the `MulticastChannel` leave the multicast group given by `group`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. func leaveGroup(_ group: SocketAddress, promise: EventLoopPromise?) @@ -60,10 +60,10 @@ public protocol MulticastChannel: Channel { /// Request that the `MulticastChannel` leave the multicast group given by `group` on the interface /// given by `interface`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - interface: The interface on which to leave the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - interface: The interface on which to leave the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. @available(*, deprecated, renamed: "leaveGroup(_:device:promise:)") func leaveGroup(_ group: SocketAddress, interface: NIONetworkInterface?, promise: EventLoopPromise?) @@ -72,10 +72,10 @@ public protocol MulticastChannel: Channel { /// Request that the `MulticastChannel` leave the multicast group given by `group` on the device /// given by `device`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - device: The device on which to leave the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - device: The device on which to leave the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. func leaveGroup(_ group: SocketAddress, device: NIONetworkDevice?, promise: EventLoopPromise?) } @@ -138,10 +138,10 @@ extension MulticastChannel { /// Request that the `MulticastChannel` join the multicast group given by `group` on the device /// given by `device`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - device: The device on which to join the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - device: The device on which to join the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. public func joinGroup(_ group: SocketAddress, device: NIONetworkDevice?, promise: EventLoopPromise?) { // We just fail this in the default implementation. Users should override it. @@ -151,10 +151,10 @@ extension MulticastChannel { /// Request that the `MulticastChannel` leave the multicast group given by `group` on the device /// given by `device`. /// - /// - parameters: - /// - group: The IP address corresponding to the relevant multicast group. - /// - device: The device on which to leave the given group, or `nil` to allow the kernel to choose. - /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or + /// - Parameters: + /// - group: The IP address corresponding to the relevant multicast group. + /// - device: The device on which to leave the given group, or `nil` to allow the kernel to choose. + /// - promise: The `EventLoopPromise` that will be notified once the operation is complete, or /// `nil` if you are not interested in the result of the operation. public func leaveGroup(_ group: SocketAddress, device: NIONetworkDevice?, promise: EventLoopPromise?) { // We just fail this in the default implementation. Users should override it. diff --git a/Sources/NIOCore/NIOAny.swift b/Sources/NIOCore/NIOAny.swift index caeda9dc98..e342c56869 100644 --- a/Sources/NIOCore/NIOAny.swift +++ b/Sources/NIOCore/NIOAny.swift @@ -80,7 +80,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `ByteBuffer`. /// - /// - returns: The wrapped `ByteBuffer` or `nil` if the wrapped message is not a `ByteBuffer`. + /// - Returns: The wrapped `ByteBuffer` or `nil` if the wrapped message is not a `ByteBuffer`. @inlinable func tryAsByteBuffer() -> ByteBuffer? { if case .ioData(.byteBuffer(let bb)) = self._storage { @@ -92,7 +92,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `ByteBuffer`. /// - /// - returns: The wrapped `ByteBuffer` or crash if the wrapped message is not a `ByteBuffer`. + /// - Returns: The wrapped `ByteBuffer` or crash if the wrapped message is not a `ByteBuffer`. @inlinable func forceAsByteBuffer() -> ByteBuffer { if let v = tryAsByteBuffer() { @@ -106,7 +106,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `IOData`. /// - /// - returns: The wrapped `IOData` or `nil` if the wrapped message is not a `IOData`. + /// - Returns: The wrapped `IOData` or `nil` if the wrapped message is not a `IOData`. @inlinable func tryAsIOData() -> IOData? { if case .ioData(let data) = self._storage { @@ -118,7 +118,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `IOData`. /// - /// - returns: The wrapped `IOData` or crash if the wrapped message is not a `IOData`. + /// - Returns: The wrapped `IOData` or crash if the wrapped message is not a `IOData`. @inlinable func forceAsIOData() -> IOData { if let v = tryAsIOData() { @@ -132,7 +132,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `FileRegion`. /// - /// - returns: The wrapped `FileRegion` or `nil` if the wrapped message is not a `FileRegion`. + /// - Returns: The wrapped `FileRegion` or `nil` if the wrapped message is not a `FileRegion`. @inlinable func tryAsFileRegion() -> FileRegion? { if case .ioData(.fileRegion(let f)) = self._storage { @@ -144,7 +144,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `FileRegion`. /// - /// - returns: The wrapped `FileRegion` or crash if the wrapped message is not a `FileRegion`. + /// - Returns: The wrapped `FileRegion` or crash if the wrapped message is not a `FileRegion`. @inlinable func forceAsFileRegion() -> FileRegion { if let v = tryAsFileRegion() { @@ -158,7 +158,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `AddressedEnvelope`. /// - /// - returns: The wrapped `AddressedEnvelope` or `nil` if the wrapped message is not an `AddressedEnvelope`. + /// - Returns: The wrapped `AddressedEnvelope` or `nil` if the wrapped message is not an `AddressedEnvelope`. @inlinable func tryAsByteEnvelope() -> AddressedEnvelope? { if case .bufferEnvelope(let e) = self._storage { @@ -170,7 +170,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `AddressedEnvelope`. /// - /// - returns: The wrapped `AddressedEnvelope` or crash if the wrapped message is not an `AddressedEnvelope`. + /// - Returns: The wrapped `AddressedEnvelope` or crash if the wrapped message is not an `AddressedEnvelope`. @inlinable func forceAsByteEnvelope() -> AddressedEnvelope { if let e = tryAsByteEnvelope() { @@ -184,7 +184,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `T`. /// - /// - returns: The wrapped `T` or `nil` if the wrapped message is not a `T`. + /// - Returns: The wrapped `T` or `nil` if the wrapped message is not a `T`. @inlinable func tryAsOther(type: T.Type = T.self) -> T? { switch self._storage { @@ -199,7 +199,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `T`. /// - /// - returns: The wrapped `T` or crash if the wrapped message is not a `T`. + /// - Returns: The wrapped `T` or crash if the wrapped message is not a `T`. @inlinable func forceAsOther(type: T.Type = T.self) -> T { if let v = tryAsOther(type: type) { @@ -213,7 +213,7 @@ public struct NIOAny { /// Force unwrapping the wrapped message as `T`. /// - /// - returns: The wrapped `T` or crash if the wrapped message is not a `T`. + /// - Returns: The wrapped `T` or crash if the wrapped message is not a `T`. @inlinable func forceAs(type: T.Type = T.self) -> T { switch T.self { @@ -232,7 +232,7 @@ public struct NIOAny { /// Try unwrapping the wrapped message as `T`. /// - /// - returns: The wrapped `T` or `nil` if the wrapped message is not a `T`. + /// - Returns: The wrapped `T` or `nil` if the wrapped message is not a `T`. @inlinable func tryAs(type: T.Type = T.self) -> T? { switch T.self { @@ -251,7 +251,7 @@ public struct NIOAny { /// Unwrap the wrapped message. /// - /// - returns: The wrapped message. + /// - Returns: The wrapped message. @inlinable func asAny() -> Any { switch self._storage { diff --git a/Sources/NIOCore/NIOLoopBound.swift b/Sources/NIOCore/NIOLoopBound.swift index 9b013ddc54..2037177d6e 100644 --- a/Sources/NIOCore/NIOLoopBound.swift +++ b/Sources/NIOCore/NIOLoopBound.swift @@ -40,7 +40,7 @@ public struct NIOLoopBound: @unchecked Sendable { /// Access the `value` with the precondition that the code is running on `eventLoop`. /// - /// - note: ``NIOLoopBound`` itself is value-typed, so any writes will only affect the current value. + /// - Note: ``NIOLoopBound`` itself is value-typed, so any writes will only affect the current value. @inlinable public var value: Value { get { @@ -129,7 +129,7 @@ public final class NIOLoopBoundBox: @unchecked Sendable { /// Access the `value` with the precondition that the code is running on `eventLoop`. /// - /// - note: ``NIOLoopBoundBox`` itself is reference-typed, so any writes will affect anybody sharing this reference. + /// - Note: ``NIOLoopBoundBox`` itself is reference-typed, so any writes will affect anybody sharing this reference. @inlinable public var value: Value { get { diff --git a/Sources/NIOCore/RecvByteBufferAllocator.swift b/Sources/NIOCore/RecvByteBufferAllocator.swift index ddce4d757e..0ab3aa3e40 100644 --- a/Sources/NIOCore/RecvByteBufferAllocator.swift +++ b/Sources/NIOCore/RecvByteBufferAllocator.swift @@ -22,9 +22,9 @@ public protocol RecvByteBufferAllocator: _NIOPreconcurrencySendable { /// Records the actual number of bytes that were read by the last socket call. /// - /// - parameters: - /// - actualReadBytes: The number of bytes that were used by the previous allocated `ByteBuffer` - /// - returns: `true` if the next call to `buffer` may return a bigger buffer then the last call to `buffer`. + /// - Parameters: + /// - actualReadBytes: The number of bytes that were used by the previous allocated `ByteBuffer` + /// - Returns: `true` if the next call to `buffer` may return a bigger buffer then the last call to `buffer`. mutating func record(actualReadBytes: Int) -> Bool } diff --git a/Sources/NIOCore/SingleStepByteToMessageDecoder.swift b/Sources/NIOCore/SingleStepByteToMessageDecoder.swift index eca2a68e14..82fcb039dd 100644 --- a/Sources/NIOCore/SingleStepByteToMessageDecoder.swift +++ b/Sources/NIOCore/SingleStepByteToMessageDecoder.swift @@ -29,9 +29,9 @@ public protocol NIOSingleStepByteToMessageDecoder: ByteToMessageDecoder { /// returned and the `ByteBuffer` contains more readable bytes, this method will immediately be invoked again, unless `decodeLast` needs /// to be invoked instead. /// - /// - parameters: - /// - buffer: The `ByteBuffer` from which we decode. - /// - returns: A message if one can be decoded or `nil` if it should be called again once more data is present in the `ByteBuffer`. + /// - Parameters: + /// - buffer: The `ByteBuffer` from which we decode. + /// - Returns: A message if one can be decoded or `nil` if it should be called again once more data is present in the `ByteBuffer`. mutating func decode(buffer: inout ByteBuffer) throws -> InboundOut? /// Decode from a `ByteBuffer` when no more data is incoming. @@ -43,10 +43,10 @@ public protocol NIOSingleStepByteToMessageDecoder: ByteToMessageDecoder { /// Once `nil` is returned, neither `decode` nor `decodeLast` will be called again. If there are no bytes left, `decodeLast` will be called /// once with an empty buffer. /// - /// - parameters: - /// - buffer: The `ByteBuffer` from which we decode. - /// - seenEOF: `true` if EOF has been seen. - /// - returns: A message if one can be decoded or `nil` if no more messages can be produced. + /// - Parameters: + /// - buffer: The `ByteBuffer` from which we decode. + /// - seenEOF: `true` if EOF has been seen. + /// - Returns: A message if one can be decoded or `nil` if no more messages can be produced. mutating func decodeLast(buffer: inout ByteBuffer, seenEOF: Bool) throws -> InboundOut? } @@ -203,9 +203,9 @@ public final class NIOSingleStepByteToMessageProcessor Void) throws { self._append(buffer) @@ -306,9 +306,9 @@ extension NIOSingleStepByteToMessageProcessor { /// Call when there is no data left in the stream. Calls `Decoder`.`decodeLast` one or more times. If there is no data left /// `decodeLast` will be called one time with an empty `ByteBuffer`. /// - /// - parameters: - /// - seenEOF: Whether an EOF was seen on the stream. - /// - messageReceiver: A closure called for each message produced by the `Decoder`. + /// - Parameters: + /// - seenEOF: Whether an EOF was seen on the stream. + /// - messageReceiver: A closure called for each message produced by the `Decoder`. @inlinable public func finishProcessing(seenEOF: Bool, _ messageReceiver: (Decoder.InboundOut) throws -> Void) throws { try self._decodeLoop(decodeMode: .last, seenEOF: seenEOF, messageReceiver) diff --git a/Sources/NIOCore/SocketAddresses.swift b/Sources/NIOCore/SocketAddresses.swift index 22479a3ba6..59fbe2f103 100644 --- a/Sources/NIOCore/SocketAddresses.swift +++ b/Sources/NIOCore/SocketAddresses.swift @@ -274,52 +274,51 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// Creates a new IPv4 `SocketAddress`. /// - /// - parameters: - /// - addr: the `sockaddr_in` that holds the ipaddress and port. - /// - host: the hostname that resolved to the ipaddress. + /// - Parameters: + /// - addr: the `sockaddr_in` that holds the ipaddress and port. + /// - host: the hostname that resolved to the ipaddress. public init(_ addr: sockaddr_in, host: String) { self = .v4(.init(address: addr, host: host)) } /// Creates a new IPv6 `SocketAddress`. /// - /// - parameters: - /// - addr: the `sockaddr_in` that holds the ipaddress and port. - /// - host: the hostname that resolved to the ipaddress. + /// - Parameters: + /// - addr: the `sockaddr_in` that holds the ipaddress and port. + /// - host: the hostname that resolved to the ipaddress. public init(_ addr: sockaddr_in6, host: String) { self = .v6(.init(address: addr, host: host)) } /// Creates a new IPv4 `SocketAddress`. /// - /// - parameters: - /// - addr: the `sockaddr_in` that holds the ipaddress and port. + /// - Parameters: + /// - addr: the `sockaddr_in` that holds the ipaddress and port. public init(_ addr: sockaddr_in) { self = .v4(.init(address: addr, host: addr.addressDescription())) } /// Creates a new IPv6 `SocketAddress`. /// - /// - parameters: - /// - addr: the `sockaddr_in` that holds the ipaddress and port. + /// - Parameters: + /// - addr: the `sockaddr_in` that holds the ipaddress and port. public init(_ addr: sockaddr_in6) { self = .v6(.init(address: addr, host: addr.addressDescription())) } /// Creates a new Unix Domain Socket `SocketAddress`. /// - /// - parameters: - /// - addr: the `sockaddr_un` that holds the socket path. + /// - Parameters: + /// - addr: the `sockaddr_un` that holds the socket path. public init(_ addr: sockaddr_un) { self = .unixDomainSocket(.init(address: addr)) } /// Creates a new UDS `SocketAddress`. /// - /// - parameters: - /// - path: the path to use for the `SocketAddress`. - /// - returns: the `SocketAddress` for the given path. - /// - throws: may throw `SocketAddressError.unixDomainSocketPathTooLong` if the path is too long. + /// - Parameters: + /// - unixDomainSocketPath: the path to use for the `SocketAddress`. + /// - Throws: may throw `SocketAddressError.unixDomainSocketPathTooLong` if the path is too long. public init(unixDomainSocketPath: String) throws { guard unixDomainSocketPath.utf8.count <= 103 else { throw SocketAddressError.unixDomainSocketPathTooLong @@ -343,11 +342,10 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// Create a new `SocketAddress` for an IP address in string form. /// - /// - parameters: - /// - string: The IP address, in string form. - /// - port: The target port. - /// - returns: the `SocketAddress` corresponding to this string and port combination. - /// - throws: may throw `SocketAddressError.failedToParseIPString` if the IP address cannot be parsed. + /// - Parameters: + /// - ipAddress: The IP address, in string form. + /// - port: The target port. + /// - Throws: may throw `SocketAddressError.failedToParseIPString` if the IP address cannot be parsed. public init(ipAddress: String, port: Int) throws { self = try ipAddress.withCString { do { @@ -387,11 +385,10 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// Create a new `SocketAddress` for an IP address in ByteBuffer form. /// - /// - parameters: - /// - packedIPAddress: The IP address, in ByteBuffer form. - /// - port: The target port. - /// - returns: the `SocketAddress` corresponding to this string and port combination. - /// - throws: may throw `SocketAddressError.failedToParseIPByteBuffer` if the IP address cannot be parsed. + /// - Parameters: + /// - packedIPAddress: The IP address, in ByteBuffer form. + /// - port: The target port. + /// - Throws: may throw `SocketAddressError.failedToParseIPByteBuffer` if the IP address cannot be parsed. public init(packedIPAddress: ByteBuffer, port: Int) throws { let packed = packedIPAddress.readableBytesView @@ -418,9 +415,9 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// As an example, consider the subnet "127.0.0.1/8". The "subnet prefix" is "8", and the corresponding netmask is "255.0.0.0". /// This initializer will produce a `SocketAddress` that contains "255.0.0.0". /// - /// - parameters: - /// - prefix: The prefix of the subnet. - /// - returns: A `SocketAddress` containing the associated netmask. + /// - Parameters: + /// - prefix: The prefix of the subnet. + /// - Returns: A `SocketAddress` containing the associated netmask. internal init(ipv4MaskForPrefix prefix: Int) { precondition((0...32).contains(prefix)) @@ -437,9 +434,9 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// As an example, consider the subnet "fe80::/10". The "subnet prefix" is "10", and the corresponding netmask is "ff30::". /// This initializer will produce a `SocketAddress` that contains "ff30::". /// - /// - parameters: - /// - prefix: The prefix of the subnet. - /// - returns: A `SocketAddress` containing the associated netmask. + /// - Parameters: + /// - prefix: The prefix of the subnet. + /// - Returns: A `SocketAddress` containing the associated netmask. internal init(ipv6MaskForPrefix prefix: Int) { precondition((0...128).contains(prefix)) @@ -462,11 +459,11 @@ public enum SocketAddress: CustomStringConvertible, Sendable { /// /// - warning: This is a blocking call, so please avoid calling this from an `EventLoop`. /// - /// - parameters: - /// - host: the hostname which should be resolved. - /// - port: the port itself - /// - returns: the `SocketAddress` for the host / port pair. - /// - throws: a `SocketAddressError.unknown` if we could not resolve the `host`, or `SocketAddressError.unsupported` if the address itself is not supported (yet). + /// - Parameters: + /// - host: the hostname which should be resolved. + /// - port: the port itself + /// - Returns: the `SocketAddress` for the host / port pair. + /// - Throws: a `SocketAddressError.unknown` if we could not resolve the `host`, or `SocketAddressError.unsupported` if the address itself is not supported (yet). public static func makeAddressResolvingHost(_ host: String, port: Int) throws -> SocketAddress { #if os(WASI) throw SocketAddressError.unsupported diff --git a/Sources/NIOCore/SocketOptionProvider.swift b/Sources/NIOCore/SocketOptionProvider.swift index 1050dbfa88..97f177298f 100644 --- a/Sources/NIOCore/SocketOptionProvider.swift +++ b/Sources/NIOCore/SocketOptionProvider.swift @@ -55,7 +55,7 @@ import WASILibc /// represents a convenient shorthand for using this protocol where the type allows, /// as well as avoiding the need to cast to this protocol. /// -/// - note: Like the `Channel` protocol, all methods in this protocol are +/// - Note: Like the `Channel` protocol, all methods in this protocol are /// thread-safe. public protocol SocketOptionProvider: _NIOPreconcurrencySendable { /// The `EventLoop` which is used by this `SocketOptionProvider` for execution. @@ -69,11 +69,11 @@ public protocol SocketOptionProvider: _NIOPreconcurrencySendable { /// and thereby read uninitialized or invalid memory. If at all possible, please use one of /// the safe functions defined by this protocol. /// - /// - parameters: - /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. - /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. - /// - value: The value to set the socket option to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. + /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. + /// - value: The value to set the socket option to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. func unsafeSetSocketOption( level: SocketOptionLevel, @@ -89,11 +89,11 @@ public protocol SocketOptionProvider: _NIOPreconcurrencySendable { /// and thereby read uninitialized or invalid memory. If at all possible, please use one of /// the safe functions defined by this protocol. /// - /// - parameters: - /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. - /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. - /// - value: The value to set the socket option to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. + /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. + /// - value: The value to set the socket option to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. func unsafeSetSocketOption( level: NIOBSDSocket.OptionLevel, @@ -109,10 +109,10 @@ public protocol SocketOptionProvider: _NIOPreconcurrencySendable { /// and thereby read uninitialized or invalid memory. If at all possible, please use one of /// the safe functions defined by this protocol. /// - /// - parameters: - /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. - /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Parameters: + /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. + /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. func unsafeGetSocketOption(level: SocketOptionLevel, name: SocketOptionName) -> EventLoopFuture #endif @@ -124,10 +124,10 @@ public protocol SocketOptionProvider: _NIOPreconcurrencySendable { /// and thereby read uninitialized or invalid memory. If at all possible, please use one of /// the safe functions defined by this protocol. /// - /// - parameters: - /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. - /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Parameters: + /// - level: The socket option level, e.g. `SOL_SOCKET` or `IPPROTO_IP`. + /// - name: The name of the socket option, e.g. `SO_REUSEADDR`. + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. func unsafeGetSocketOption( level: NIOBSDSocket.OptionLevel, @@ -178,9 +178,9 @@ public typealias NIOLinger = linger extension SocketOptionProvider { /// Sets the socket option SO_LINGER to `value`. /// - /// - parameters: - /// - value: The value to set SO_LINGER to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set SO_LINGER to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setSoLinger(_ value: linger) -> EventLoopFuture { #if os(WASI) @@ -192,7 +192,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option SO_LINGER. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getSoLinger() -> EventLoopFuture { #if os(WASI) @@ -204,9 +204,9 @@ extension SocketOptionProvider { /// Sets the socket option IP_MULTICAST_IF to `value`. /// - /// - parameters: - /// - value: The value to set IP_MULTICAST_IF to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IP_MULTICAST_IF to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPMulticastIF(_ value: in_addr) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ip, name: .ip_multicast_if, value: value) @@ -214,7 +214,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IP_MULTICAST_IF. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPMulticastIF() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ip, name: .ip_multicast_if) @@ -222,9 +222,9 @@ extension SocketOptionProvider { /// Sets the socket option IP_MULTICAST_TTL to `value`. /// - /// - parameters: - /// - value: The value to set IP_MULTICAST_TTL to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IP_MULTICAST_TTL to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPMulticastTTL(_ value: CUnsignedChar) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ip, name: .ip_multicast_ttl, value: value) @@ -232,7 +232,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IP_MULTICAST_TTL. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPMulticastTTL() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ip, name: .ip_multicast_ttl) @@ -240,9 +240,9 @@ extension SocketOptionProvider { /// Sets the socket option IP_MULTICAST_LOOP to `value`. /// - /// - parameters: - /// - value: The value to set IP_MULTICAST_LOOP to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IP_MULTICAST_LOOP to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPMulticastLoop(_ value: CUnsignedChar) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ip, name: .ip_multicast_loop, value: value) @@ -250,7 +250,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IP_MULTICAST_LOOP. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPMulticastLoop() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ip, name: .ip_multicast_loop) @@ -258,9 +258,9 @@ extension SocketOptionProvider { /// Sets the socket option IPV6_MULTICAST_IF to `value`. /// - /// - parameters: - /// - value: The value to set IPV6_MULTICAST_IF to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IPV6_MULTICAST_IF to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPv6MulticastIF(_ value: CUnsignedInt) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ipv6, name: .ipv6_multicast_if, value: value) @@ -268,7 +268,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IPV6_MULTICAST_IF. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPv6MulticastIF() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ipv6, name: .ipv6_multicast_if) @@ -276,9 +276,9 @@ extension SocketOptionProvider { /// Sets the socket option IPV6_MULTICAST_HOPS to `value`. /// - /// - parameters: - /// - value: The value to set IPV6_MULTICAST_HOPS to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IPV6_MULTICAST_HOPS to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPv6MulticastHops(_ value: CInt) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ipv6, name: .ipv6_multicast_hops, value: value) @@ -286,7 +286,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IPV6_MULTICAST_HOPS. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPv6MulticastHops() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ipv6, name: .ipv6_multicast_hops) @@ -294,9 +294,9 @@ extension SocketOptionProvider { /// Sets the socket option IPV6_MULTICAST_LOOP to `value`. /// - /// - parameters: - /// - value: The value to set IPV6_MULTICAST_LOOP to. - /// - returns: An `EventLoopFuture` that fires when the option has been set, + /// - Parameters: + /// - value: The value to set IPV6_MULTICAST_LOOP to. + /// - Returns: An `EventLoopFuture` that fires when the option has been set, /// or if an error has occurred. public func setIPv6MulticastLoop(_ value: CUnsignedInt) -> EventLoopFuture { self.unsafeSetSocketOption(level: .ipv6, name: .ipv6_multicast_loop, value: value) @@ -304,7 +304,7 @@ extension SocketOptionProvider { /// Gets the value of the socket option IPV6_MULTICAST_LOOP. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getIPv6MulticastLoop() -> EventLoopFuture { self.unsafeGetSocketOption(level: .ipv6, name: .ipv6_multicast_loop) @@ -315,7 +315,7 @@ extension SocketOptionProvider { /// /// This socket option cannot be set. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getTCPInfo() -> EventLoopFuture { self.unsafeGetSocketOption(level: .tcp, name: .tcp_info) @@ -327,7 +327,7 @@ extension SocketOptionProvider { /// /// This socket option cannot be set. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getTCPConnectionInfo() -> EventLoopFuture { self.unsafeGetSocketOption(level: .tcp, name: .tcp_connection_info) @@ -339,7 +339,7 @@ extension SocketOptionProvider { /// /// This socket option cannot be set. /// - /// - returns: An `EventLoopFuture` containing the value of the socket option, or + /// - Returns: An `EventLoopFuture` containing the value of the socket option, or /// any error that occurred while retrieving the socket option. public func getMPTCPInfo() -> EventLoopFuture { self.unsafeGetSocketOption(level: .mptcp, name: .mptcp_info) diff --git a/Sources/NIOCore/TimeAmount+Duration.swift b/Sources/NIOCore/TimeAmount+Duration.swift index fb3011fe5f..bd5f25ef9f 100644 --- a/Sources/NIOCore/TimeAmount+Duration.swift +++ b/Sources/NIOCore/TimeAmount+Duration.swift @@ -16,7 +16,7 @@ extension TimeAmount { @available(macOS 13, iOS 16, tvOS 16, watchOS 9, *) /// Creates a new `TimeAmount` for the given `Duration`, truncating and clamping if necessary. /// - /// - returns: `TimeAmount`, truncated to nanosecond precision, and clamped to `Int64.max` nanoseconds. + /// - Returns: `TimeAmount`, truncated to nanosecond precision, and clamped to `Int64.max` nanoseconds. public init(_ duration: Swift.Duration) { self = .nanoseconds(duration.nanosecondsClamped) } @@ -25,8 +25,6 @@ extension TimeAmount { @available(macOS 13, iOS 16, tvOS 16, watchOS 9, *) extension Swift.Duration { /// Construct a `Duration` given a number of nanoseconds represented as a `TimeAmount`. - /// - /// - returns: A `Duration` representing a given number of nanoseconds. public init(_ timeAmount: TimeAmount) { self = .nanoseconds(timeAmount.nanoseconds) } diff --git a/Sources/NIOCore/UniversalBootstrapSupport.swift b/Sources/NIOCore/UniversalBootstrapSupport.swift index 16a04f7733..c3083781ba 100644 --- a/Sources/NIOCore/UniversalBootstrapSupport.swift +++ b/Sources/NIOCore/UniversalBootstrapSupport.swift @@ -30,8 +30,8 @@ public protocol NIOClientTCPBootstrapProtocol { /// might be called multiple times and it's important not to share stateful `ChannelHandler`s in more /// than one `Channel`. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. @preconcurrency func channelInitializer(_ handler: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self @@ -46,42 +46,42 @@ public protocol NIOClientTCPBootstrapProtocol { /// Specifies a `ChannelOption` to be applied to the `SocketChannel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. func channelOption(_ option: Option, value: Option.Value) -> Self /// Apply any understood convenience options to the bootstrap, removing them from the set of options if they are consumed. /// Method is optional to implement and should never be directly called by users. - /// - parameters: - /// - options: The options to try applying - the options applied should be consumed from here. - /// - returns: The updated bootstrap with and options applied. + /// - Parameters: + /// - options: The options to try applying - the options applied should be consumed from here. + /// - Returns: The updated bootstrap with and options applied. func _applyChannelConvenienceOptions(_ options: inout ChannelOptions.TCPConvenienceOptions) -> Self - /// - parameters: - /// - timeout: The timeout that will apply to the connection attempt. + /// - Parameters: + /// - timeout: The timeout that will apply to the connection attempt. func connectTimeout(_ timeout: TimeAmount) -> Self /// Specify the `host` and `port` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - host: The host to connect to. - /// - port: The port to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - host: The host to connect to. + /// - port: The port to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. func connect(host: String, port: Int) -> EventLoopFuture /// Specify the `address` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - address: The address to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - address: The address to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. func connect(to address: SocketAddress) -> EventLoopFuture /// Specify the `unixDomainSocket` path to connect to for the UDS `Channel` that will be established. /// - /// - parameters: - /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. func connect(unixDomainSocketPath: String) -> EventLoopFuture } @@ -148,12 +148,12 @@ public struct NIOClientTCPBootstrap { /// Initialize a `NIOClientTCPBootstrap` using the underlying `Bootstrap` alongside a compatible `TLS` /// implementation. /// - /// - note: If you do not require `TLS`, you can use `NIOInsecureNoTLS` which supports only plain-text + /// - Note: If you do not require `TLS`, you can use `NIOInsecureNoTLS` which supports only plain-text /// connections. We highly recommend to always use TLS. /// - /// - parameters: - /// - bootstrap: The underlying bootstrap to use. - /// - tls: The TLS implementation to use, needs to be compatible with `Bootstrap`. + /// - Parameters: + /// - bootstrap: The underlying bootstrap to use. + /// - tls: The TLS implementation to use, needs to be compatible with `Bootstrap`. public init< Bootstrap: NIOClientTCPBootstrapProtocol, TLS: NIOClientTLSProvider @@ -192,8 +192,8 @@ public struct NIOClientTCPBootstrap { /// might be called multiple times and it's important not to share stateful `ChannelHandler`s in more /// than one `Channel`. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. public func channelInitializer( _ handler: @escaping @Sendable (Channel) -> EventLoopFuture ) -> NIOClientTCPBootstrap { @@ -205,9 +205,9 @@ public struct NIOClientTCPBootstrap { /// Specifies a `ChannelOption` to be applied to the `SocketChannel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. public func channelOption(_ option: Option, value: Option.Value) -> NIOClientTCPBootstrap { NIOClientTCPBootstrap( self.underlyingBootstrap.channelOption(option, value: value), @@ -215,8 +215,8 @@ public struct NIOClientTCPBootstrap { ) } - /// - parameters: - /// - timeout: The timeout that will apply to the connection attempt. + /// - Parameters: + /// - timeout: The timeout that will apply to the connection attempt. public func connectTimeout(_ timeout: TimeAmount) -> NIOClientTCPBootstrap { NIOClientTCPBootstrap( self.underlyingBootstrap.connectTimeout(timeout), @@ -226,28 +226,28 @@ public struct NIOClientTCPBootstrap { /// Specify the `host` and `port` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - host: The host to connect to. - /// - port: The port to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - host: The host to connect to. + /// - port: The port to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(host: String, port: Int) -> EventLoopFuture { self.underlyingBootstrap.connect(host: host, port: port) } /// Specify the `address` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - address: The address to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - address: The address to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(to address: SocketAddress) -> EventLoopFuture { self.underlyingBootstrap.connect(to: address) } /// Specify the `unixDomainSocket` path to connect to for the UDS `Channel` that will be established. /// - /// - parameters: - /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(unixDomainSocketPath: String) -> EventLoopFuture { self.underlyingBootstrap.connect(unixDomainSocketPath: unixDomainSocketPath) } diff --git a/Sources/NIOCore/Utilities.swift b/Sources/NIOCore/Utilities.swift index 795aa3ff42..5ed6c2f30d 100644 --- a/Sources/NIOCore/Utilities.swift +++ b/Sources/NIOCore/Utilities.swift @@ -81,7 +81,7 @@ public enum System { /// On Linux the value returned will take account of cgroup or cpuset restrictions. /// The result will be rounded up to the nearest whole number where fractional CPUs have been assigned. /// - /// - returns: The logical core count on the system. + /// - Returns: The logical core count on the system. public static var coreCount: Int { #if os(Windows) var dwLength: DWORD = 0 @@ -138,8 +138,8 @@ public enum System { /// change, and the returned values will not change to reflect them. This function must be called /// again to get new results. /// - /// - returns: An array of network interfaces available on this machine. - /// - throws: If an error is encountered while enumerating interfaces. + /// - Returns: An array of network interfaces available on this machine. + /// - Throws: If an error is encountered while enumerating interfaces. @available(*, deprecated, renamed: "enumerateDevices") public static func enumerateInterfaces() throws -> [NIONetworkInterface] { var interfaces: [NIONetworkInterface] = [] @@ -169,8 +169,8 @@ public enum System { /// change, and the returned values will not change to reflect them. This function must be called /// again to get new results. /// - /// - returns: An array of network devices available on this machine. - /// - throws: If an error is encountered while enumerating interfaces. + /// - Returns: An array of network devices available on this machine. + /// - Throws: If an error is encountered while enumerating interfaces. public static func enumerateDevices() throws -> [NIONetworkDevice] { var devices: [NIONetworkDevice] = [] devices.reserveCapacity(12) // Arbitrary choice. diff --git a/Sources/NIOEmbedded/AsyncTestingChannel.swift b/Sources/NIOEmbedded/AsyncTestingChannel.swift index 7b676077a3..75889e5c37 100644 --- a/Sources/NIOEmbedded/AsyncTestingChannel.swift +++ b/Sources/NIOEmbedded/AsyncTestingChannel.swift @@ -80,7 +80,7 @@ import NIOCore /// using writeInbound() using readOutbound() /// ``` /// -/// - note: ``NIOAsyncTestingChannel`` is currently only compatible with +/// - Note: ``NIOAsyncTestingChannel`` is currently only compatible with /// ``NIOAsyncTestingEventLoop``s and cannot be used with `SelectableEventLoop`s from /// for example `MultiThreadedEventLoopGroup`. @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) @@ -168,7 +168,7 @@ public final class NIOAsyncTestingChannel: Channel { /// /// An active ``NIOAsyncTestingChannel`` can be closed by calling `close` or ``finish()`` on the ``NIOAsyncTestingChannel``. /// - /// - note: An ``NIOAsyncTestingChannel`` starts _inactive_ and can be activated, for example by calling `connect`. + /// - Note: An ``NIOAsyncTestingChannel`` starts _inactive_ and can be activated, for example by calling `connect`. public var isActive: Bool { channelcore.isActive } /// - see: `ChannelOptions.Types.AllowRemoteHalfClosureOption` @@ -268,8 +268,8 @@ public final class NIOAsyncTestingChannel: Channel { /// /// During creation it will automatically also register itself on the ``NIOAsyncTestingEventLoop``. /// - /// - parameters: - /// - loop: The ``NIOAsyncTestingEventLoop`` to use. + /// - Parameters: + /// - loop: The ``NIOAsyncTestingEventLoop`` to use. public init(loop: NIOAsyncTestingEventLoop = NIOAsyncTestingEventLoop()) { self.testingEventLoop = loop self._pipeline = ChannelPipeline(channel: self) @@ -280,9 +280,9 @@ public final class NIOAsyncTestingChannel: Channel { /// /// During creation it will automatically also register itself on the ``NIOAsyncTestingEventLoop``. /// - /// - parameters: - /// - handler: The `ChannelHandler` to add to the `ChannelPipeline` before register. - /// - loop: The ``NIOAsyncTestingEventLoop`` to use. + /// - Parameters: + /// - handler: The `ChannelHandler` to add to the `ChannelPipeline` before register. + /// - loop: The ``NIOAsyncTestingEventLoop`` to use. public convenience init(handler: ChannelHandler, loop: NIOAsyncTestingEventLoop = NIOAsyncTestingEventLoop()) async { await self.init(handlers: [handler], loop: loop) @@ -292,9 +292,9 @@ public final class NIOAsyncTestingChannel: Channel { /// /// During creation it will automatically also register itself on the ``NIOAsyncTestingEventLoop``. /// - /// - parameters: - /// - handlers: The `ChannelHandler`s to add to the `ChannelPipeline` before register. - /// - loop: The ``NIOAsyncTestingEventLoop`` to use. + /// - Parameters: + /// - handlers: The `ChannelHandler`s to add to the `ChannelPipeline` before register. + /// - loop: The ``NIOAsyncTestingEventLoop`` to use. public convenience init( handlers: [ChannelHandler], loop: NIOAsyncTestingEventLoop = NIOAsyncTestingEventLoop() @@ -311,9 +311,9 @@ public final class NIOAsyncTestingChannel: Channel { /// /// Errors in the ``NIOAsyncTestingChannel`` can be consumed using ``throwIfErrorCaught()``. /// - /// - parameters: - /// - acceptAlreadyClosed: Whether ``finish()`` should throw if the ``NIOAsyncTestingChannel`` has been previously `close`d. - /// - returns: The ``LeftOverState`` of the ``NIOAsyncTestingChannel``. If all the inbound and outbound events have been + /// - Parameters: + /// - acceptAlreadyClosed: Whether ``finish()`` should throw if the ``NIOAsyncTestingChannel`` has been previously `close`d. + /// - Returns: The ``LeftOverState`` of the ``NIOAsyncTestingChannel``. If all the inbound and outbound events have been /// consumed (using ``readInbound(as:)`` / ``readOutbound(as:)``) and there are no pending outbound events (unflushed /// writes) this will be ``LeftOverState/clean``. If there are any unconsumed inbound, outbound, or pending outbound /// events, the ``NIOAsyncTestingChannel`` will returns those as ``LeftOverState/leftOvers(inbound:outbound:pendingOutbound:)``. @@ -353,7 +353,7 @@ public final class NIOAsyncTestingChannel: Channel { /// This method will throw if the `Channel` hit any unconsumed errors or if the `close` fails. Errors in the /// ``NIOAsyncTestingChannel`` can be consumed using ``throwIfErrorCaught()``. /// - /// - returns: The ``LeftOverState`` of the ``NIOAsyncTestingChannel``. If all the inbound and outbound events have been + /// - Returns: The ``LeftOverState`` of the ``NIOAsyncTestingChannel``. If all the inbound and outbound events have been /// consumed (using ``readInbound(as:)`` / ``readOutbound(as:)``) and there are no pending outbound events (unflushed /// writes) this will be ``LeftOverState/clean``. If there are any unconsumed inbound, outbound, or pending outbound /// events, the ``NIOAsyncTestingChannel`` will returns those as ``LeftOverState/leftOvers(inbound:outbound:pendingOutbound:)``. @@ -370,8 +370,8 @@ public final class NIOAsyncTestingChannel: Channel { /// first `ChannelHandler` must have written and flushed it either explicitly (by calling /// `ChannelHandlerContext.write` and `flush`) or implicitly by not implementing `write`/`flush`. /// - /// - note: Outbound events travel the `ChannelPipeline` _back to front_. - /// - note: ``NIOAsyncTestingChannel/writeOutbound(_:)`` will `write` data through the `ChannelPipeline`, starting with last + /// - Note: Outbound events travel the `ChannelPipeline` _back to front_. + /// - Note: ``NIOAsyncTestingChannel/writeOutbound(_:)`` will `write` data through the `ChannelPipeline`, starting with last /// `ChannelHandler`. @inlinable public func readOutbound(as type: T.Type = T.self) async throws -> T? { @@ -390,8 +390,8 @@ public final class NIOAsyncTestingChannel: Channel { /// first `ChannelHandler` must have written and flushed it either explicitly (by calling /// `ChannelHandlerContext.write` and `flush`) or implicitly by not implementing `write`/`flush`. /// - /// - note: Outbound events travel the `ChannelPipeline` _back to front_. - /// - note: ``NIOAsyncTestingChannel/writeOutbound(_:)`` will `write` data through the `ChannelPipeline`, starting with last + /// - Note: Outbound events travel the `ChannelPipeline` _back to front_. + /// - Note: ``NIOAsyncTestingChannel/writeOutbound(_:)`` will `write` data through the `ChannelPipeline`, starting with last /// `ChannelHandler`. public func waitForOutboundWrite(as type: T.Type = T.self) async throws -> T { try await withCheckedThrowingContinuation { continuation in @@ -424,7 +424,7 @@ public final class NIOAsyncTestingChannel: Channel { /// last `ChannelHandler` must have send the event either explicitly (by calling /// `ChannelHandlerContext.fireChannelRead`) or implicitly by not implementing `channelRead`. /// - /// - note: ``NIOAsyncTestingChannel/writeInbound(_:)`` will fire data through the `ChannelPipeline` using `fireChannelRead`. + /// - Note: ``NIOAsyncTestingChannel/writeInbound(_:)`` will fire data through the `ChannelPipeline` using `fireChannelRead`. @inlinable public func readInbound(as type: T.Type = T.self) async throws -> T? { try await self.testingEventLoop.executeInContext { @@ -442,7 +442,7 @@ public final class NIOAsyncTestingChannel: Channel { /// last `ChannelHandler` must have send the event either explicitly (by calling /// `ChannelHandlerContext.fireChannelRead`) or implicitly by not implementing `channelRead`. /// - /// - note: ``NIOAsyncTestingChannel/writeInbound(_:)`` will fire data through the `ChannelPipeline` using `fireChannelRead`. + /// - Note: ``NIOAsyncTestingChannel/writeInbound(_:)`` will fire data through the `ChannelPipeline` using `fireChannelRead`. public func waitForInboundWrite(as type: T.Type = T.self) async throws -> T { try await withCheckedThrowingContinuation { continuation in self.testingEventLoop.execute { @@ -470,9 +470,9 @@ public final class NIOAsyncTestingChannel: Channel { /// The immediate effect being that the first `ChannelInboundHandler` will get its `channelRead` method called /// with the data you provide. /// - /// - parameters: + /// - Parameters: /// - data: The data to fire through the pipeline. - /// - returns: The state of the inbound buffer which contains all the events that travelled the `ChannelPipeline` + /// - Returns: The state of the inbound buffer which contains all the events that travelled the `ChannelPipeline` // all the way. @inlinable @discardableResult public func writeInbound(_ data: T) async throws -> BufferState { @@ -490,9 +490,9 @@ public final class NIOAsyncTestingChannel: Channel { /// with the data you provide. Note that the first `ChannelOutboundHandler` in the pipeline is the _last_ handler /// because outbound events travel the pipeline from back to front. /// - /// - parameters: + /// - Parameters: /// - data: The data to fire through the pipeline. - /// - returns: The state of the outbound buffer which contains all the events that travelled the `ChannelPipeline` + /// - Returns: The state of the outbound buffer which contains all the events that travelled the `ChannelPipeline` // all the way. @inlinable @discardableResult public func writeOutbound(_ data: T) async throws -> BufferState { @@ -596,9 +596,9 @@ public final class NIOAsyncTestingChannel: Channel { /// happens when it travels the `ChannelPipeline` all the way to the front, this will also set the /// ``NIOAsyncTestingChannel``'s ``localAddress``. /// - /// - parameters: - /// - address: The address to fake-bind to. - /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. + /// - Parameters: + /// - address: The address to fake-bind to. + /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. public func bind(to address: SocketAddress, promise: EventLoopPromise?) { promise?.futureResult.whenSuccess { self.localAddress = address @@ -616,9 +616,9 @@ public final class NIOAsyncTestingChannel: Channel { /// which happens when it travels the `ChannelPipeline` all the way to the front, this will also set the /// ``NIOAsyncTestingChannel``'s ``remoteAddress``. /// - /// - parameters: - /// - address: The address to fake-bind to. - /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. + /// - Parameters: + /// - address: The address to fake-bind to. + /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. public func connect(to address: SocketAddress, promise: EventLoopPromise?) { promise?.futureResult.whenSuccess { self.remoteAddress = address diff --git a/Sources/NIOEmbedded/Embedded.swift b/Sources/NIOEmbedded/Embedded.swift index d2f2b7652b..c509a8ffa3 100644 --- a/Sources/NIOEmbedded/Embedded.swift +++ b/Sources/NIOEmbedded/Embedded.swift @@ -590,7 +590,7 @@ class EmbeddedChannelCore: ChannelCore { /// `EmbeddedChannel` automatically collects arriving outbound data and makes it /// available one-by-one through `readOutbound`. /// -/// - note: `EmbeddedChannel` is currently only compatible with +/// - Note: `EmbeddedChannel` is currently only compatible with /// `EmbeddedEventLoop`s and cannot be used with `SelectableEventLoop`s from /// for example `MultiThreadedEventLoopGroup`. /// - warning: Unlike other `Channel`s, `EmbeddedChannel` **is not thread-safe**. This @@ -681,7 +681,7 @@ public final class EmbeddedChannel: Channel { /// /// An active `EmbeddedChannel` can be closed by calling `close` or `finish` on the `EmbeddedChannel`. /// - /// - note: An `EmbeddedChannel` starts _inactive_ and can be activated, for example by calling `connect`. + /// - Note: An `EmbeddedChannel` starts _inactive_ and can be activated, for example by calling `connect`. public var isActive: Bool { channelcore.isActive } /// - see: `ChannelOptions.Types.AllowRemoteHalfClosureOption` @@ -724,9 +724,9 @@ public final class EmbeddedChannel: Channel { /// /// Errors in the `EmbeddedChannel` can be consumed using `throwIfErrorCaught`. /// - /// - parameters: - /// - acceptAlreadyClosed: Whether `finish` should throw if the `EmbeddedChannel` has been previously `close`d. - /// - returns: The `LeftOverState` of the `EmbeddedChannel`. If all the inbound and outbound events have been + /// - Parameters: + /// - acceptAlreadyClosed: Whether `finish` should throw if the `EmbeddedChannel` has been previously `close`d. + /// - Returns: The `LeftOverState` of the `EmbeddedChannel`. If all the inbound and outbound events have been /// consumed (using `readInbound` / `readOutbound`) and there are no pending outbound events (unflushed /// writes) this will be `.clean`. If there are any unconsumed inbound, outbound, or pending outbound /// events, the `EmbeddedChannel` will returns those as `.leftOvers(inbound:outbound:pendingOutbound:)`. @@ -759,7 +759,7 @@ public final class EmbeddedChannel: Channel { /// This method will throw if the `Channel` hit any unconsumed errors or if the `close` fails. Errors in the /// `EmbeddedChannel` can be consumed using `throwIfErrorCaught`. /// - /// - returns: The `LeftOverState` of the `EmbeddedChannel`. If all the inbound and outbound events have been + /// - Returns: The `LeftOverState` of the `EmbeddedChannel`. If all the inbound and outbound events have been /// consumed (using `readInbound` / `readOutbound`) and there are no pending outbound events (unflushed /// writes) this will be `.clean`. If there are any unconsumed inbound, outbound, or pending outbound /// events, the `EmbeddedChannel` will returns those as `.leftOvers(inbound:outbound:pendingOutbound:)`. @@ -819,8 +819,8 @@ public final class EmbeddedChannel: Channel { /// first `ChannelHandler` must have written and flushed it either explicitly (by calling /// `ChannelHandlerContext.write` and `flush`) or implicitly by not implementing `write`/`flush`. /// - /// - note: Outbound events travel the `ChannelPipeline` _back to front_. - /// - note: `EmbeddedChannel.writeOutbound` will `write` data through the `ChannelPipeline`, starting with last + /// - Note: Outbound events travel the `ChannelPipeline` _back to front_. + /// - Note: `EmbeddedChannel.writeOutbound` will `write` data through the `ChannelPipeline`, starting with last /// `ChannelHandler`. @inlinable public func readOutbound(as type: T.Type = T.self) throws -> T? { @@ -837,7 +837,7 @@ public final class EmbeddedChannel: Channel { /// last `ChannelHandler` must have send the event either explicitly (by calling /// `ChannelHandlerContext.fireChannelRead`) or implicitly by not implementing `channelRead`. /// - /// - note: `EmbeddedChannel.writeInbound` will fire data through the `ChannelPipeline` using `fireChannelRead`. + /// - Note: `EmbeddedChannel.writeInbound` will fire data through the `ChannelPipeline` using `fireChannelRead`. @inlinable public func readInbound(as type: T.Type = T.self) throws -> T? { self.embeddedEventLoop.checkCorrectThread() @@ -849,9 +849,9 @@ public final class EmbeddedChannel: Channel { /// The immediate effect being that the first `ChannelInboundHandler` will get its `channelRead` method called /// with the data you provide. /// - /// - parameters: + /// - Parameters: /// - data: The data to fire through the pipeline. - /// - returns: The state of the inbound buffer which contains all the events that travelled the `ChannelPipeline` + /// - Returns: The state of the inbound buffer which contains all the events that travelled the `ChannelPipeline` // all the way. @inlinable @discardableResult public func writeInbound(_ data: T) throws -> BufferState { @@ -868,9 +868,9 @@ public final class EmbeddedChannel: Channel { /// with the data you provide. Note that the first `ChannelOutboundHandler` in the pipeline is the _last_ handler /// because outbound events travel the pipeline from back to front. /// - /// - parameters: + /// - Parameters: /// - data: The data to fire through the pipeline. - /// - returns: The state of the outbound buffer which contains all the events that travelled the `ChannelPipeline` + /// - Returns: The state of the outbound buffer which contains all the events that travelled the `ChannelPipeline` // all the way. @inlinable @discardableResult public func writeOutbound(_ data: T) throws -> BufferState { @@ -910,9 +910,9 @@ public final class EmbeddedChannel: Channel { /// /// During creation it will automatically also register itself on the `EmbeddedEventLoop`. /// - /// - parameters: - /// - handler: The `ChannelHandler` to add to the `ChannelPipeline` before register or `nil` if none should be added. - /// - loop: The `EmbeddedEventLoop` to use. + /// - Parameters: + /// - handler: The `ChannelHandler` to add to the `ChannelPipeline` before register or `nil` if none should be added. + /// - loop: The `EmbeddedEventLoop` to use. public convenience init(handler: ChannelHandler? = nil, loop: EmbeddedEventLoop = EmbeddedEventLoop()) { let handlers = handler.map { [$0] } ?? [] self.init(handlers: handlers, loop: loop) @@ -923,9 +923,9 @@ public final class EmbeddedChannel: Channel { /// /// During creation it will automatically also register itself on the `EmbeddedEventLoop`. /// - /// - parameters: - /// - handlers: The `ChannelHandler`s to add to the `ChannelPipeline` before register. - /// - loop: The `EmbeddedEventLoop` to use. + /// - Parameters: + /// - handlers: The `ChannelHandler`s to add to the `ChannelPipeline` before register. + /// - loop: The `EmbeddedEventLoop` to use. public init(handlers: [ChannelHandler], loop: EmbeddedEventLoop = EmbeddedEventLoop()) { self.embeddedEventLoop = loop self._pipeline = ChannelPipeline(channel: self) @@ -987,9 +987,9 @@ public final class EmbeddedChannel: Channel { /// happens when it travels the `ChannelPipeline` all the way to the front, this will also set the /// `EmbeddedChannel`'s `localAddress`. /// - /// - parameters: - /// - address: The address to fake-bind to. - /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. + /// - Parameters: + /// - address: The address to fake-bind to. + /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. public func bind(to address: SocketAddress, promise: EventLoopPromise?) { self.embeddedEventLoop.checkCorrectThread() promise?.futureResult.whenSuccess { @@ -1002,9 +1002,9 @@ public final class EmbeddedChannel: Channel { /// which happens when it travels the `ChannelPipeline` all the way to the front, this will also set the /// `EmbeddedChannel`'s `remoteAddress`. /// - /// - parameters: - /// - address: The address to fake-bind to. - /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. + /// - Parameters: + /// - address: The address to fake-bind to. + /// - promise: The `EventLoopPromise` which will be fulfilled when the fake-bind operation has been done. public func connect(to address: SocketAddress, promise: EventLoopPromise?) { self.embeddedEventLoop.checkCorrectThread() promise?.futureResult.whenSuccess { diff --git a/Sources/NIOFileSystem/BufferedWriter.swift b/Sources/NIOFileSystem/BufferedWriter.swift index 9763525cf0..23683ea086 100644 --- a/Sources/NIOFileSystem/BufferedWriter.swift +++ b/Sources/NIOFileSystem/BufferedWriter.swift @@ -121,7 +121,7 @@ public struct BufferedWriter { /// /// To manually flush bytes use ``flush()``. /// - /// - Parameter bytes: The `AsyncSequence` of byte chunks to write to the buffer. + /// - Parameter chunks: The `AsyncSequence` of byte chunks to write to the buffer. /// - Returns: The number of bytes written into the buffered writer. @discardableResult public mutating func write( @@ -157,7 +157,7 @@ public struct BufferedWriter { /// /// To manually flush bytes use ``flush()``. /// - /// - Parameter bytes: The `AsyncSequence` of `ByteBuffer`s to write. + /// - Parameter chunks: The `AsyncSequence` of `ByteBuffer`s to write. /// - Returns: The number of bytes written into the buffered writer. @discardableResult public mutating func write( diff --git a/Sources/NIOFileSystem/FileHandleProtocol.swift b/Sources/NIOFileSystem/FileHandleProtocol.swift index 3251de175f..c331b80817 100644 --- a/Sources/NIOFileSystem/FileHandleProtocol.swift +++ b/Sources/NIOFileSystem/FileHandleProtocol.swift @@ -155,8 +155,8 @@ public protocol FileHandleProtocol { /// > The seconds component must also be positive: if it's not, zero will be used as the value instead. /// /// - Parameters: - /// - lastAccessTime: The new value of the file's last access time, as time elapsed since the Epoch. - /// - lastDataModificationTime: The new value of the file's last data modification time, as time elapsed since the Epoch. + /// - lastAccess: The new value of the file's last access time, as time elapsed since the Epoch. + /// - lastDataModification: The new value of the file's last data modification time, as time elapsed since the Epoch. /// /// - Throws: If there's an error updating the times. If this happens, the original values won't be modified. func setTimes( @@ -212,7 +212,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6`` /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -227,7 +226,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6`` /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -242,7 +240,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6``. /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -258,7 +255,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6``. /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -274,7 +270,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6``. /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -290,7 +285,6 @@ extension ReadableFileHandleProtocol { /// - Parameters: /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6``. /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -303,9 +297,7 @@ extension ReadableFileHandleProtocol { /// Returns an asynchronous sequence of chunks read from the file. /// /// - Parameters: - /// - range: A range of offsets in the file to read. /// - chunkLength: The length of chunks to read, defaults to 128 KiB. - /// - as: Type of chunk to read. /// - SeeAlso: ``ReadableFileHandleProtocol/readChunks(in:chunkLength:)-2dz6``. /// - Returns: An `AsyncSequence` of chunks read from the file. public func readChunks( @@ -757,6 +749,7 @@ extension DirectoryFileHandleProtocol { /// /// - Parameters: /// - path: The path of the directory to open. + /// - options: How the directory should be opened. /// - body: A closure which provides access to the directory. /// - Important: The handle passed to `execute` must not escape the closure. /// - Returns: The result of the `execute` closure. diff --git a/Sources/NIOFileSystem/FileSystem.swift b/Sources/NIOFileSystem/FileSystem.swift index 64de1b8669..76a1bcb8a9 100644 --- a/Sources/NIOFileSystem/FileSystem.swift +++ b/Sources/NIOFileSystem/FileSystem.swift @@ -189,6 +189,7 @@ public struct FileSystem: Sendable, FileSystemProtocol { /// /// - Parameters: /// - path: The path of the directory to open. + /// - options: How the directory should be opened. /// - Returns: A handle to the opened directory. public func openDirectory( atPath path: FilePath, @@ -387,6 +388,7 @@ public struct FileSystem: Sendable, FileSystemProtocol { /// /// - Parameters: /// - path: The path to delete. + /// - removeItemRecursively: Whether or not to remove items recursively. /// - Returns: The number of deleted items which may be zero if `path` did not exist. @discardableResult public func removeItem( @@ -546,7 +548,7 @@ public struct FileSystem: Sendable, FileSystemProtocol { /// Uses the `link(2)` system call. /// /// - Parameters: - /// - path: The path at which to create the symbolic link. + /// - linkPath: The path at which to create the symbolic link. /// - destinationPath: The path that contains the item that the symbolic link points to.` public func createSymbolicLink( at linkPath: FilePath, @@ -647,7 +649,7 @@ extension NIOSingletons { /// The thread count is the system's available core count unless the environment variable /// `NIO_SINGLETON_FILESYSTEM_THREAD_COUNT` is set or this value was set manually by the user. /// - /// - note: This value must be set _before_ any singletons are used and must only be set once. + /// - Note: This value must be set _before_ any singletons are used and must only be set once. @available(*, deprecated, renamed: "blockingPoolThreadCountSuggestion") public static var fileSystemThreadCountSuggestion: Int { set { Self.blockingPoolThreadCountSuggestion = newValue } diff --git a/Sources/NIOFileSystem/FileSystemProtocol.swift b/Sources/NIOFileSystem/FileSystemProtocol.swift index e420a4d10a..b5bf701435 100644 --- a/Sources/NIOFileSystem/FileSystemProtocol.swift +++ b/Sources/NIOFileSystem/FileSystemProtocol.swift @@ -77,6 +77,7 @@ public protocol FileSystemProtocol: Sendable { /// /// - Parameters: /// - path: The path of the directory to open. + /// - options: How the directory should be opened. /// - Returns: A handle to the opened directory. func openDirectory( atPath path: FilePath, @@ -181,7 +182,7 @@ public protocol FileSystemProtocol: Sendable { /// - Parameters: /// - sourcePath: The path to the item to copy. /// - destinationPath: The path at which to place the copy. - /// - strategy: How to deal with concurrent aspects of the copy, only relevant to directories. + /// - copyStrategy: How to deal with concurrent aspects of the copy, only relevant to directories. /// - shouldProceedAfterError: A closure which is executed to determine whether to continue /// copying files if an error is encountered during the operation. See Errors section for full details. /// - shouldCopyItem: A closure which is executed before each copy to determine whether each diff --git a/Sources/NIOFoundationCompat/ByteBuffer-foundation.swift b/Sources/NIOFoundationCompat/ByteBuffer-foundation.swift index 7aedfb17b0..8b221d75cb 100644 --- a/Sources/NIOFoundationCompat/ByteBuffer-foundation.swift +++ b/Sources/NIOFoundationCompat/ByteBuffer-foundation.swift @@ -55,9 +55,9 @@ extension ByteBuffer { /// underlying storage from the returned `Data` value. If you want manual control over the byte transferring /// behaviour, please use `readData(length:byteTransferStrategy:)`. /// - /// - parameters: - /// - length: The number of bytes to be read from this `ByteBuffer`. - /// - returns: A `Data` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. + /// - Parameters: + /// - length: The number of bytes to be read from this `ByteBuffer`. + /// - Returns: A `Data` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. public mutating func readData(length: Int) -> Data? { self.readData(length: length, byteTransferStrategy: .automatic) } @@ -65,11 +65,11 @@ extension ByteBuffer { /// Read `length` bytes off this `ByteBuffer`, move the reader index forward by `length` bytes and return the result /// as `Data`. /// - /// - parameters: - /// - length: The number of bytes to be read from this `ByteBuffer`. - /// - byteTransferStrategy: Controls how to transfer the bytes. See `ByteTransferStrategy` for an explanation + /// - Parameters: + /// - length: The number of bytes to be read from this `ByteBuffer`. + /// - byteTransferStrategy: Controls how to transfer the bytes. See `ByteTransferStrategy` for an explanation /// of the options. - /// - returns: A `Data` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. + /// - Returns: A `Data` value containing `length` bytes or `nil` if there aren't at least `length` bytes readable. public mutating func readData(length: Int, byteTransferStrategy: ByteTransferStrategy) -> Data? { guard let result = self.getData(at: self.readerIndex, length: length, byteTransferStrategy: byteTransferStrategy) @@ -87,10 +87,10 @@ extension ByteBuffer { /// underlying storage from the returned `Data` value. If you want manual control over the byte transferring /// behaviour, please use `getData(at:byteTransferStrategy:)`. /// - /// - parameters: - /// - index: The starting index of the bytes of interest into the `ByteBuffer` - /// - length: The number of bytes of interest - /// - returns: A `Data` value containing the bytes of interest or `nil` if the selected bytes are not readable. + /// - Parameters: + /// - index: The starting index of the bytes of interest into the `ByteBuffer` + /// - length: The number of bytes of interest + /// - Returns: A `Data` value containing the bytes of interest or `nil` if the selected bytes are not readable. public func getData(at index: Int, length: Int) -> Data? { self.getData(at: index, length: length, byteTransferStrategy: .automatic) } @@ -98,14 +98,14 @@ extension ByteBuffer { /// Return `length` bytes starting at `index` and return the result as `Data`. This will not change the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index of the bytes of interest into the `ByteBuffer` - /// - length: The number of bytes of interest - /// - byteTransferStrategy: Controls how to transfer the bytes. See `ByteTransferStrategy` for an explanation + /// - Parameters: + /// - index: The starting index of the bytes of interest into the `ByteBuffer` + /// - length: The number of bytes of interest + /// - byteTransferStrategy: Controls how to transfer the bytes. See `ByteTransferStrategy` for an explanation /// of the options. - /// - returns: A `Data` value containing the bytes of interest or `nil` if the selected bytes are not readable. - public func getData(at index0: Int, length: Int, byteTransferStrategy: ByteTransferStrategy) -> Data? { - let index = index0 - self.readerIndex + /// - Returns: A `Data` value containing the bytes of interest or `nil` if the selected bytes are not readable. + public func getData(at index: Int, length: Int, byteTransferStrategy: ByteTransferStrategy) -> Data? { + let index = index - self.readerIndex guard index >= 0 && length >= 0 && index <= self.readableBytes - length else { return nil } @@ -141,11 +141,11 @@ extension ByteBuffer { /// Get a `String` decoding `length` bytes starting at `index` with `encoding`. This will not change the reader index. /// The selected bytes must be readable or else `nil` will be returned. /// - /// - parameters: - /// - index: The starting index of the bytes of interest into the `ByteBuffer`. - /// - length: The number of bytes of interest. - /// - encoding: The `String` encoding to be used. - /// - returns: A `String` value containing the bytes of interest or `nil` if the selected bytes are not readable or + /// - Parameters: + /// - index: The starting index of the bytes of interest into the `ByteBuffer`. + /// - length: The number of bytes of interest. + /// - encoding: The `String` encoding to be used. + /// - Returns: A `String` value containing the bytes of interest or `nil` if the selected bytes are not readable or /// cannot be decoded with the given encoding. public func getString(at index: Int, length: Int, encoding: String.Encoding) -> String? { guard let data = self.getData(at: index, length: length) else { @@ -156,10 +156,10 @@ extension ByteBuffer { /// Read a `String` decoding `length` bytes with `encoding` from the `readerIndex`, moving the `readerIndex` appropriately. /// - /// - parameters: - /// - length: The number of bytes to read. - /// - encoding: The `String` encoding to be used. - /// - returns: A `String` value containing the bytes of interest or `nil` if the `ByteBuffer` doesn't contain enough bytes, or + /// - Parameters: + /// - length: The number of bytes to read. + /// - encoding: The `String` encoding to be used. + /// - Returns: A `String` value containing the bytes of interest or `nil` if the `ByteBuffer` doesn't contain enough bytes, or /// if those bytes cannot be decoded with the given encoding. public mutating func readString(length: Int, encoding: String.Encoding) -> String? { guard length <= self.readableBytes else { @@ -175,10 +175,10 @@ extension ByteBuffer { /// Write `string` into this `ByteBuffer` using the encoding `encoding`, moving the writer index forward appropriately. /// - /// - parameters: - /// - string: The string to write. - /// - encoding: The encoding to use to encode the string. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - encoding: The encoding to use to encode the string. + /// - Returns: The number of bytes written. @discardableResult public mutating func writeString(_ string: String, encoding: String.Encoding) throws -> Int { let written = try self.setString(string, encoding: encoding, at: self.writerIndex) @@ -188,11 +188,11 @@ extension ByteBuffer { /// Write `string` into this `ByteBuffer` at `index` using the encoding `encoding`. Does not move the writer index. /// - /// - parameters: - /// - string: The string to write. - /// - encoding: The encoding to use to encode the string. - /// - index: The index for the first serialized byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - string: The string to write. + /// - encoding: The encoding to use to encode the string. + /// - index: The index for the first serialized byte. + /// - Returns: The number of bytes written. @discardableResult public mutating func setString(_ string: String, encoding: String.Encoding, at index: Int) throws -> Int { guard let data = string.data(using: encoding) else { @@ -208,9 +208,9 @@ extension ByteBuffer { // MARK: ContiguousBytes and DataProtocol /// Write `bytes` into this `ByteBuffer` at the writer index, moving the writer index forward appropriately. /// - /// - parameters: - /// - bytes: The bytes to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - bytes: The bytes to write. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func writeContiguousBytes(_ bytes: Bytes) -> Int { @@ -221,10 +221,10 @@ extension ByteBuffer { /// Write `bytes` into this `ByteBuffer` at `index`. Does not move the writer index. /// - /// - parameters: - /// - bytes: The bytes to write. - /// - index: The index for the first byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - bytes: The bytes to write. + /// - index: The index for the first byte. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func setContiguousBytes(_ bytes: Bytes, at index: Int) -> Int { @@ -235,9 +235,9 @@ extension ByteBuffer { /// Write the bytes of `data` into this `ByteBuffer` at the writer index, moving the writer index forward appropriately. /// - /// - parameters: - /// - data: The data to write. - /// - returns: The number of bytes written. + /// - Parameters: + /// - data: The data to write. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func writeData(_ data: D) -> Int { @@ -248,10 +248,10 @@ extension ByteBuffer { /// Write the bytes of `data` into this `ByteBuffer` at `index`. Does not move the writer index. /// - /// - parameters: - /// - data: The data to write. - /// - index: The index for the first byte. - /// - returns: The number of bytes written. + /// - Parameters: + /// - data: The data to write. + /// - index: The index for the first byte. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func setData(_ data: D, at index: Int) -> Int { @@ -399,7 +399,10 @@ extension ByteBufferView { extension Data { /// Creates a `Data` from a given `ByteBuffer`. The entire readable portion of the buffer will be read. - /// - parameter buffer: The buffer to read. + /// - Parameters: + /// - buffer: The buffer to read. + /// - byteTransferStrategy: Controls how to transfer the bytes. See `ByteTransferStrategy` for an explanation + /// of the options. public init(buffer: ByteBuffer, byteTransferStrategy: ByteBuffer.ByteTransferStrategy = .automatic) { var buffer = buffer self = buffer.readData(length: buffer.readableBytes, byteTransferStrategy: byteTransferStrategy)! diff --git a/Sources/NIOFoundationCompat/Codable+ByteBuffer.swift b/Sources/NIOFoundationCompat/Codable+ByteBuffer.swift index 0f61ad0ae1..5e22a414f4 100644 --- a/Sources/NIOFoundationCompat/Codable+ByteBuffer.swift +++ b/Sources/NIOFoundationCompat/Codable+ByteBuffer.swift @@ -18,12 +18,12 @@ import NIOCore extension ByteBuffer { /// Attempts to decode the `length` bytes from `index` using the `JSONDecoder` `decoder` as `T`. /// - /// - parameters: + /// - Parameters: /// - type: The type type that is attempted to be decoded. /// - decoder: The `JSONDecoder` that is used for the decoding. /// - index: The index of the first byte to decode. /// - length: The number of bytes to decode. - /// - returns: The decoded value if successful or `nil` if there are not enough readable bytes available. + /// - Returns: The decoded value if successful or `nil` if there are not enough readable bytes available. @inlinable public func getJSONDecodable( _ type: T.Type, @@ -39,11 +39,11 @@ extension ByteBuffer { /// Reads `length` bytes from this `ByteBuffer` and then attempts to decode them using the `JSONDecoder` `decoder`. /// - /// - parameters: + /// - Parameters: /// - type: The type type that is attempted to be decoded. /// - decoder: The `JSONDecoder` that is used for the decoding. /// - length: The number of bytes to decode. - /// - returns: The decoded value is successful or `nil` if there are not enough readable bytes available. + /// - Returns: The decoded value is successful or `nil` if there are not enough readable bytes available. @inlinable public mutating func readJSONDecodable( _ type: T.Type, @@ -67,12 +67,13 @@ extension ByteBuffer { /// Encodes `value` using the `JSONEncoder` `encoder` and set the resulting bytes into this `ByteBuffer` at the /// given `index`. /// - /// - note: The `writerIndex` remains unchanged. + /// - Note: The `writerIndex` remains unchanged. /// - /// - parameters: - /// - value: An `Encodable` value to encode. - /// - encoder: The `JSONEncoder` to encode `value` with. - /// - returns: The number of bytes written. + /// - Parameters: + /// - value: An `Encodable` value to encode. + /// - encoder: The `JSONEncoder` to encode `value` with. + /// - index: The starting index of the bytes for the value into the `ByteBuffer`. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func setJSONEncodable( @@ -88,10 +89,10 @@ extension ByteBuffer { /// /// If successful, this will move the writer index forward by the number of bytes written. /// - /// - parameters: - /// - value: An `Encodable` value to encode. - /// - encoder: The `JSONEncoder` to encode `value` with. - /// - returns: The number of bytes written. + /// - Parameters: + /// - value: An `Encodable` value to encode. + /// - encoder: The `JSONEncoder` to encode `value` with. + /// - Returns: The number of bytes written. @inlinable @discardableResult public mutating func writeJSONEncodable( @@ -111,13 +112,13 @@ extension JSONDecoder { /// `DecodingError.dataCorrupted(_:)` error. If a value within the JSON /// fails to decode, this method throws the corresponding error. /// - /// - note: The provided `ByteBuffer` remains unchanged, neither the `readerIndex` nor the `writerIndex` will move. + /// - Note: The provided `ByteBuffer` remains unchanged, neither the `readerIndex` nor the `writerIndex` will move. /// If you would like the `readerIndex` to move, consider using `ByteBuffer.readJSONDecodable(_:length:)`. /// - /// - parameters: - /// - type: The type of the value to decode from the supplied JSON object. - /// - buffer: The `ByteBuffer` that contains JSON object to decode. - /// - returns: The decoded object. + /// - Parameters: + /// - type: The type of the value to decode from the supplied JSON object. + /// - buffer: The `ByteBuffer` that contains JSON object to decode. + /// - Returns: The decoded object. public func decode(_ type: T.Type, from buffer: ByteBuffer) throws -> T { try buffer.getJSONDecodable( T.self, @@ -131,9 +132,9 @@ extension JSONDecoder { extension JSONEncoder { /// Writes a JSON-encoded representation of the value you supply into the supplied `ByteBuffer`. /// - /// - parameters: - /// - value: The value to encode as JSON. - /// - buffer: The `ByteBuffer` to encode into. + /// - Parameters: + /// - value: The value to encode as JSON. + /// - buffer: The `ByteBuffer` to encode into. public func encode( _ value: T, into buffer: inout ByteBuffer @@ -143,10 +144,10 @@ extension JSONEncoder { /// Writes a JSON-encoded representation of the value you supply into a `ByteBuffer` that is freshly allocated. /// - /// - parameters: - /// - value: The value to encode as JSON. - /// - allocator: The `ByteBufferAllocator` which is used to allocate the `ByteBuffer` to be returned. - /// - returns: The `ByteBuffer` containing the encoded JSON. + /// - Parameters: + /// - value: The value to encode as JSON. + /// - allocator: The `ByteBufferAllocator` which is used to allocate the `ByteBuffer` to be returned. + /// - Returns: The `ByteBuffer` containing the encoded JSON. public func encodeAsByteBuffer(_ value: T, allocator: ByteBufferAllocator) throws -> ByteBuffer { let data = try self.encode(value) var buffer = allocator.buffer(capacity: data.count) diff --git a/Sources/NIOFoundationCompat/JSONSerialization+ByteBuffer.swift b/Sources/NIOFoundationCompat/JSONSerialization+ByteBuffer.swift index d8f00438ca..661a931f9f 100644 --- a/Sources/NIOFoundationCompat/JSONSerialization+ByteBuffer.swift +++ b/Sources/NIOFoundationCompat/JSONSerialization+ByteBuffer.swift @@ -19,15 +19,15 @@ extension JSONSerialization { /// Attempts to derive a Foundation object from a ByteBuffer and return it as `T`. /// - /// - parameters: + /// - Parameters: /// - buffer: The ByteBuffer being used to derive the Foundation type. /// - options: The reading option used when the parser derives the Foundation type from the ByteBuffer. - /// - returns: The Foundation value if successful or `nil` if there was an issue creating the Foundation type. + /// - Returns: The Foundation value if successful or `nil` if there was an issue creating the Foundation type. @inlinable public static func jsonObject( with buffer: ByteBuffer, - options opt: JSONSerialization.ReadingOptions = [] + options: JSONSerialization.ReadingOptions = [] ) throws -> Any { - try JSONSerialization.jsonObject(with: Data(buffer: buffer), options: opt) + try JSONSerialization.jsonObject(with: Data(buffer: buffer), options: options) } } diff --git a/Sources/NIOHTTP1/HTTPDecoder.swift b/Sources/NIOHTTP1/HTTPDecoder.swift index eb33c620ba..a38c775cf4 100644 --- a/Sources/NIOHTTP1/HTTPDecoder.swift +++ b/Sources/NIOHTTP1/HTTPDecoder.swift @@ -541,8 +541,8 @@ public final class HTTPDecoder: ByteToMessageDecoder, HTTPDecoderDelega /// Creates a new instance of `HTTPDecoder`. /// - /// - parameters: - /// - leftOverBytesStrategy: The strategy to use when removing the decoder from the pipeline and an upgrade was, + /// - Parameters: + /// - leftOverBytesStrategy: The strategy to use when removing the decoder from the pipeline and an upgrade was, /// detected. Note that this does not affect what happens on EOF. public convenience init(leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes) { self.init(leftOverBytesStrategy: leftOverBytesStrategy, informationalResponseStrategy: .drop) @@ -550,10 +550,10 @@ public final class HTTPDecoder: ByteToMessageDecoder, HTTPDecoderDelega /// Creates a new instance of `HTTPDecoder`. /// - /// - parameters: - /// - leftOverBytesStrategy: The strategy to use when removing the decoder from the pipeline and an upgrade was, + /// - Parameters: + /// - leftOverBytesStrategy: The strategy to use when removing the decoder from the pipeline and an upgrade was, /// detected. Note that this does not affect what happens on EOF. - /// - informationalResponseStrategy: Should informational responses (like http status 100) be forwarded or dropped. + /// - informationalResponseStrategy: Should informational responses (like http status 100) be forwarded or dropped. /// Default is `.drop`. This property is only respected when decoding responses. public init( leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes, diff --git a/Sources/NIOHTTP1/HTTPPipelineSetup.swift b/Sources/NIOHTTP1/HTTPPipelineSetup.swift index 419dcc275d..a789b8f6a1 100644 --- a/Sources/NIOHTTP1/HTTPPipelineSetup.swift +++ b/Sources/NIOHTTP1/HTTPPipelineSetup.swift @@ -36,11 +36,11 @@ public typealias NIOHTTPServerUpgradeConfiguration = ( extension ChannelPipeline { /// Configure a `ChannelPipeline` for use as a HTTP client. /// - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. public func addHTTPClientHandlers( position: Position = .last, leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes @@ -54,15 +54,15 @@ extension ChannelPipeline { /// Configure a `ChannelPipeline` for use as a HTTP client with a client upgrader configuration. /// - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - upgrade: Add a `HTTPClientUpgradeHandler` to the pipeline, configured for + /// - upgrade: Add a `HTTPClientUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of `HTTPClientProtocolUpgrader` and /// the upgrade completion handler. See the documentation on `HTTPClientUpgradeHandler` /// for more details. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. @preconcurrency public func addHTTPClientHandlers( position: Position = .last, @@ -107,17 +107,17 @@ extension ChannelPipeline { /// Configure a `ChannelPipeline` for use as a HTTP client. /// - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - enableOutboundHeaderValidation: Whether the pipeline should confirm that outbound headers are well-formed. + /// - enableOutboundHeaderValidation: Whether the pipeline should confirm that outbound headers are well-formed. /// Defaults to `true`. - /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for + /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientUpgradeHandler`` and /// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler`` /// for more details. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. public func addHTTPClientHandlers( position: Position = .last, leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes, @@ -152,18 +152,18 @@ extension ChannelPipeline { /// Configure a `ChannelPipeline` for use as a HTTP client. /// - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - enableOutboundHeaderValidation: Whether the pipeline should confirm that outbound headers are well-formed. + /// - enableOutboundHeaderValidation: Whether the pipeline should confirm that outbound headers are well-formed. /// Defaults to `true`. - /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. - /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for + /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. + /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientUpgradeHandler`` and /// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler`` /// for more details. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. public func addHTTPClientHandlers( position: Position = .last, leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes, @@ -211,19 +211,19 @@ extension ChannelPipeline { /// This method will likely be extended in future with more support for other first-party /// features. /// - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. @preconcurrency public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, @@ -253,21 +253,21 @@ extension ChannelPipeline { /// This method will likely be extended in future with more support for other first-party /// features. /// - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - headerValidation: Whether to validate outbound request headers to confirm that they meet + /// - headerValidation: Whether to validate outbound request headers to confirm that they meet /// spec compliance. Defaults to `true`. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, withPipeliningAssistance pipelining: Bool = true, @@ -298,22 +298,22 @@ extension ChannelPipeline { /// This method will likely be extended in future with more support for other first-party /// features. /// - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - headerValidation: Whether to validate outbound request headers to confirm that they meet + /// - headerValidation: Whether to validate outbound request headers to confirm that they meet /// spec compliance. Defaults to `true`. - /// - encoderConfiguration: The configuration for the ``HTTPResponseEncoder``. - /// - returns: An `EventLoopFuture` that will fire when the pipeline is configured. + /// - encoderConfiguration: The configuration for the ``HTTPResponseEncoder``. + /// - Returns: An `EventLoopFuture` that will fire when the pipeline is configured. public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, withPipeliningAssistance pipelining: Bool = true, @@ -375,15 +375,15 @@ extension ChannelPipeline.SynchronousOperations { /// Configure a `ChannelPipeline` for use as a HTTP client with a client upgrader configuration. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - upgrade: Add a `HTTPClientUpgradeHandler` to the pipeline, configured for + /// - upgrade: Add a `HTTPClientUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of `HTTPClientProtocolUpgrader` and /// the upgrade completion handler. See the documentation on `HTTPClientUpgradeHandler` /// for more details. - /// - throws: If the pipeline could not be configured. + /// - Throws: If the pipeline could not be configured. @preconcurrency public func addHTTPClientHandlers( position: ChannelPipeline.Position = .last, @@ -400,15 +400,16 @@ extension ChannelPipeline.SynchronousOperations { /// Configure a `ChannelPipeline` for use as a HTTP client. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for + /// - enableOutboundHeaderValidation: Whether or not request header validation is enforced. + /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientProtocolUpgrader`` and /// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler`` /// for more details. - /// - throws: If the pipeline could not be configured. + /// - Throws: If the pipeline could not be configured. public func addHTTPClientHandlers( position: ChannelPipeline.Position = .last, leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes, @@ -426,16 +427,17 @@ extension ChannelPipeline.SynchronousOperations { /// Configure a `ChannelPipeline` for use as a HTTP client. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. - /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` + /// - Parameters: + /// - position: The position in the `ChannelPipeline` where to add the HTTP client handlers. Defaults to `.last`. + /// - leftOverBytesStrategy: The strategy to use when dealing with leftover bytes after removing the `HTTPDecoder` /// from the pipeline. - /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. - /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for + /// - enableOutboundHeaderValidation: Whether or not request header validation is enforced. + /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. + /// - upgrade: Add a ``NIOHTTPClientUpgradeHandler`` to the pipeline, configured for /// HTTP upgrade. Should be a tuple of an array of ``NIOHTTPClientProtocolUpgrader`` and /// the upgrade completion handler. See the documentation on ``NIOHTTPClientUpgradeHandler`` /// for more details. - /// - throws: If the pipeline could not be configured. + /// - Throws: If the pipeline could not be configured. public func addHTTPClientHandlers( position: ChannelPipeline.Position = .last, leftOverBytesStrategy: RemoveAfterUpgradeStrategy = .dropBytes, @@ -533,19 +535,19 @@ extension ChannelPipeline.SynchronousOperations { /// features. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - throws: If the pipeline could not be configured. + /// - Throws: If the pipeline could not be configured. @preconcurrency public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, @@ -576,21 +578,21 @@ extension ChannelPipeline.SynchronousOperations { /// features. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - headerValidation: Whether to validate outbound request headers to confirm that they meet + /// - headerValidation: Whether to validate outbound request headers to confirm that they meet /// spec compliance. Defaults to `true`. - /// - throws: If the pipeline could not be configured. + /// - Throws: If the pipeline could not be configured. public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, withPipeliningAssistance pipelining: Bool = true, @@ -622,22 +624,22 @@ extension ChannelPipeline.SynchronousOperations { /// features. /// /// - important: This **must** be called on the Channel's event loop. - /// - parameters: - /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. - /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline + /// - Parameters: + /// - position: Where in the pipeline to add the HTTP server handlers, defaults to `.last`. + /// - pipelining: Whether to provide assistance handling HTTP clients that pipeline /// their requests. Defaults to `true`. If `false`, users will need to handle /// clients that pipeline themselves. - /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for + /// - upgrade: Whether to add a `HTTPServerUpgradeHandler` to the pipeline, configured for /// HTTP upgrade. Defaults to `nil`, which will not add the handler to the pipeline. If /// provided should be a tuple of an array of `HTTPServerProtocolUpgrader` and the upgrade /// completion handler. See the documentation on `HTTPServerUpgradeHandler` for more /// details. - /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. + /// - errorHandling: Whether to provide assistance handling protocol errors (e.g. /// failure to parse the HTTP request) by sending 400 errors. Defaults to `true`. - /// - headerValidation: Whether to validate outbound request headers to confirm that they meet + /// - headerValidation: Whether to validate outbound request headers to confirm that they meet /// spec compliance. Defaults to `true`. - /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. - /// - throws: If the pipeline could not be configured. + /// - encoderConfiguration: The configuration for the ``HTTPRequestEncoder``. + /// - Throws: If the pipeline could not be configured. public func configureHTTPServerPipeline( position: ChannelPipeline.Position = .last, withPipeliningAssistance pipelining: Bool = true, diff --git a/Sources/NIOHTTP1/HTTPServerUpgradeHandler.swift b/Sources/NIOHTTP1/HTTPServerUpgradeHandler.swift index 1a92370c3d..cadaff37c3 100644 --- a/Sources/NIOHTTP1/HTTPServerUpgradeHandler.swift +++ b/Sources/NIOHTTP1/HTTPServerUpgradeHandler.swift @@ -194,7 +194,7 @@ public final class HTTPServerUpgradeHandler: ChannelInboundHandler, RemovableCha /// The core of the upgrade handling logic. /// - /// - returns: An `EventLoopFuture` that will contain a callback to invoke if upgrade is requested, or nil if upgrade has failed. Never returns a failed future. + /// - Returns: An `EventLoopFuture` that will contain a callback to invoke if upgrade is requested, or nil if upgrade has failed. Never returns a failed future. private func handleUpgrade( context: ChannelHandlerContext, request: HTTPRequestHead, diff --git a/Sources/NIOHTTP1/HTTPTypes.swift b/Sources/NIOHTTP1/HTTPTypes.swift index a10abaccb2..321b494d6d 100644 --- a/Sources/NIOHTTP1/HTTPTypes.swift +++ b/Sources/NIOHTTP1/HTTPTypes.swift @@ -93,11 +93,11 @@ public struct HTTPRequestHead: Equatable { /// Create a `HTTPRequestHead` /// - /// - parameters: - /// - version: The version for this HTTP request. - /// - method: The HTTP method for this request. - /// - uri: The URI used on this request. - /// - headers: This request's HTTP headers. + /// - Parameters: + /// - version: The version for this HTTP request. + /// - method: The HTTP method for this request. + /// - uri: The URI used on this request. + /// - headers: This request's HTTP headers. public init(version: HTTPVersion, method: HTTPMethod, uri: String, headers: HTTPHeaders) { self._storage = .init(method: method, uri: uri, version: version) self.headers = headers @@ -331,9 +331,9 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// Construct a `HTTPHeaders` structure. /// - /// - parameters - /// - headers: An initial set of headers to use to populate the header block. - /// - allocator: The allocator to use to allocate the underlying storage. + /// - Parameters + /// - headers: An initial set of headers to use to populate the header block. + /// - allocator: The allocator to use to allocate the underlying storage. public init(_ headers: [(String, String)] = []) { // Note: this initializer exists because of https://bugs.swift.org/browse/SR-7415. // Otherwise we'd only have the one below with a default argument for `allocator`. @@ -342,8 +342,8 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// Construct a `HTTPHeaders` structure. /// - /// - parameters - /// - elements: name, value pairs provided by a dictionary literal. + /// - Parameters + /// - elements: name, value pairs provided by a dictionary literal. public init(dictionaryLiteral elements: (String, String)...) { self.init(elements) } @@ -370,7 +370,7 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// This method is strictly additive: if there are other entries with the same header /// name already in the block, this will add new entries. /// - /// - Parameter contentsOf: The sequence of header name/value pairs. For maximum compatibility + /// - Parameter other: The sequence of header name/value pairs. For maximum compatibility /// the header should be an ASCII string. For future-proofing with HTTP/2 lowercase header /// names are strongly recommended. @inlinable @@ -383,7 +383,7 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// Add another block of headers to the block. /// - /// - Parameter contentsOf: The block of headers to add to these headers. + /// - Parameter other: The block of headers to add to these headers. public mutating func add(contentsOf other: HTTPHeaders) { self.headers.append(contentsOf: other.headers) if other.keepAliveState == .unknown { @@ -417,16 +417,16 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// This method uses case-insensitive comparisons for the header field name. /// /// - Parameter name: The name of the header field to remove from the block. - public mutating func remove(name nameToRemove: String) { - if self.isConnectionHeader(nameToRemove) { + public mutating func remove(name: String) { + if self.isConnectionHeader(name) { self.keepAliveState = .unknown } - self.headers.removeAll { (name, _) in - if nameToRemove.utf8.count != name.utf8.count { + self.headers.removeAll { (headerName, _) in + if name.utf8.count != headerName.utf8.count { return false } - return nameToRemove.utf8.compareCaseInsensitiveASCIIBytes(to: name.utf8) + return name.utf8.compareCaseInsensitiveASCIIBytes(to: headerName.utf8) } } @@ -471,8 +471,8 @@ public struct HTTPHeaders: CustomStringConvertible, ExpressibleByDictionaryLiter /// Checks if a header is present /// - /// - parameters: - /// - name: The name of the header + /// - Parameters: + /// - name: The name of the header // - returns: `true` if a header with the name (and value) exists, `false` otherwise. public func contains(name: String) -> Bool { for kv in self.headers { diff --git a/Sources/NIOHTTP1/NIOTypedHTTPServerUpgradeHandler.swift b/Sources/NIOHTTP1/NIOTypedHTTPServerUpgradeHandler.swift index dd08789a6d..e22a57a806 100644 --- a/Sources/NIOHTTP1/NIOTypedHTTPServerUpgradeHandler.swift +++ b/Sources/NIOHTTP1/NIOTypedHTTPServerUpgradeHandler.swift @@ -106,12 +106,12 @@ public final class NIOTypedHTTPServerUpgradeHandler: Ch /// /// - Parameters: /// - httpEncoder: The ``HTTPResponseEncoder`` encoding responses from this handler and which will - /// be removed from the pipeline once the upgrade response is sent. This is used to ensure - /// that the pipeline will be in a clean state after upgrade. - /// - extraHTTPHandlers: Any other handlers that are directly related to handling HTTP. At the very least - /// this should include the `HTTPDecoder`, but should also include any other handler that cannot tolerate - /// receiving non-HTTP data. - /// - upgradeConfiguration: The upgrade configuration. + /// be removed from the pipeline once the upgrade response is sent. This is used to ensure + /// that the pipeline will be in a clean state after upgrade. + /// - extraHTTPHandlers: Any other handlers that are directly related to handling HTTP. At the very least + /// this should include the `HTTPDecoder`, but should also include any other handler that cannot tolerate + /// receiving non-HTTP data. + /// - upgradeConfiguration: The upgrade configuration. public init( httpEncoder: HTTPResponseEncoder, extraHTTPHandlers: [RemovableChannelHandler], diff --git a/Sources/NIOPosix/BSDSocketAPICommon.swift b/Sources/NIOPosix/BSDSocketAPICommon.swift index 538d919afe..0465ed54af 100644 --- a/Sources/NIOPosix/BSDSocketAPICommon.swift +++ b/Sources/NIOPosix/BSDSocketAPICommon.swift @@ -161,7 +161,7 @@ extension NIOBSDSocket.ProtocolSubtype { /// The protocol subtype for MPTCP. /// - /// - returns: nil if MPTCP is not supported. + /// - Returns: nil if MPTCP is not supported. public static var mptcp: Self? { #if os(Linux) // Defined by the linux kernel, this is IPPROTO_MPTCP. diff --git a/Sources/NIOPosix/BaseSocket.swift b/Sources/NIOPosix/BaseSocket.swift index 489fec44de..bc6663445f 100644 --- a/Sources/NIOPosix/BaseSocket.swift +++ b/Sources/NIOPosix/BaseSocket.swift @@ -125,8 +125,8 @@ class BaseSocket: BaseSocketProtocol { /// Returns the local bound `SocketAddress` of the socket. /// - /// - returns: The local bound address. - /// - throws: An `IOError` if the retrieval of the address failed. + /// - Returns: The local bound address. + /// - Throws: An `IOError` if the retrieval of the address failed. func localAddress() throws -> SocketAddress { try get_addr { try NIOBSDSocket.getsockname(socket: $0, address: $1, address_len: $2) @@ -135,8 +135,8 @@ class BaseSocket: BaseSocketProtocol { /// Returns the connected `SocketAddress` of the socket. /// - /// - returns: The connected address. - /// - throws: An `IOError` if the retrieval of the address failed. + /// - Returns: The connected address. + /// - Throws: An `IOError` if the retrieval of the address failed. func remoteAddress() throws -> SocketAddress { try get_addr { try NIOBSDSocket.getpeername(socket: $0, address: $1, address_len: $2) @@ -161,12 +161,12 @@ class BaseSocket: BaseSocketProtocol { /// Create a new socket and return the file descriptor of it. /// - /// - parameters: - /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). - /// - type: The type of the socket to create. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - returns: the file descriptor of the socket that was created. - /// - throws: An `IOError` if creation of the socket failed. + /// - Parameters: + /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). + /// - type: The type of the socket to create. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Returns: the file descriptor of the socket that was created. + /// - Throws: An `IOError` if creation of the socket failed. static func makeSocket( protocolFamily: NIOBSDSocket.ProtocolFamily, type: NIOBSDSocket.SocketType, @@ -223,9 +223,9 @@ class BaseSocket: BaseSocketProtocol { /// /// Deletes the associated file if it exists and has socket type. Does nothing if pathname does not exist. /// - /// - parameters: - /// - unixDomainSocketPath: The pathname of the UDS. - /// - throws: An `UnixDomainSocketPathWrongType` if the pathname exists and is not a socket. + /// - Parameters: + /// - unixDomainSocketPath: The pathname of the UDS. + /// - Throws: An `UnixDomainSocketPathWrongType` if the pathname exists and is not a socket. static func cleanupSocket(unixDomainSocketPath: String) throws { try NIOBSDSocket.cleanupUnixDomainSocket(atPath: unixDomainSocketPath) } @@ -235,8 +235,8 @@ class BaseSocket: BaseSocketProtocol { /// The ownership of the passed in descriptor is transferred to this class. A user must call `close` to close the underlying /// file descriptor once it's not needed / used anymore. /// - /// - parameters: - /// - descriptor: The file descriptor to wrap. + /// - Parameters: + /// - descriptor: The file descriptor to wrap. init(socket descriptor: NIOBSDSocket.Handle) throws { #if os(Windows) precondition(descriptor != NIOBSDSocket.invalidHandle, "invalid socket") @@ -276,11 +276,11 @@ class BaseSocket: BaseSocketProtocol { /// /// This basically just delegates to `setsockopt` syscall. /// - /// - parameters: - /// - level: The protocol level (see `man setsockopt`). - /// - name: The name of the option to set. - /// - value: The value for the option. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - level: The protocol level (see `man setsockopt`). + /// - name: The name of the option to set. + /// - value: The value for the option. + /// - Throws: An `IOError` if the operation failed. func setOption(level: NIOBSDSocket.OptionLevel, name: NIOBSDSocket.Option, value: T) throws { if level == .tcp && name == .tcp_nodelay { switch try? self.localAddress().protocol { @@ -309,10 +309,10 @@ class BaseSocket: BaseSocketProtocol { /// /// This basically just delegates to `getsockopt` syscall. /// - /// - parameters: - /// - level: The protocol level (see `man getsockopt`). - /// - name: The name of the option to set. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - level: The protocol level (see `man getsockopt`). + /// - name: The name of the option to set. + /// - Throws: An `IOError` if the operation failed. func getOption(level: NIOBSDSocket.OptionLevel, name: NIOBSDSocket.Option) throws -> T { try self.withUnsafeHandle { fd in var length = socklen_t(MemoryLayout.size) @@ -342,9 +342,9 @@ class BaseSocket: BaseSocketProtocol { /// Bind the socket to the given `SocketAddress`. /// - /// - parameters: - /// - address: The `SocketAddress` to which the socket should be bound. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - address: The `SocketAddress` to which the socket should be bound. + /// - Throws: An `IOError` if the operation failed. func bind(to address: SocketAddress) throws { try self.withUnsafeHandle { fd in try address.withSockAddr { @@ -357,7 +357,7 @@ class BaseSocket: BaseSocketProtocol { /// /// After the socket was closed all other methods will throw an `IOError` when called. /// - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. func close() throws { try NIOBSDSocket.close(socket: try self.takeDescriptorOwnership()) } @@ -367,7 +367,7 @@ class BaseSocket: BaseSocketProtocol { /// After this call, `BaseSocket` considers itself to be closed and the caller is responsible for actually closing /// the underlying file descriptor. /// - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. final func takeDescriptorOwnership() throws -> NIOBSDSocket.Handle { try self.withUnsafeHandle { self.descriptor = NIOBSDSocket.invalidHandle diff --git a/Sources/NIOPosix/BaseSocketChannel.swift b/Sources/NIOPosix/BaseSocketChannel.swift index 4f8e4454b7..164d5802bd 100644 --- a/Sources/NIOPosix/BaseSocketChannel.swift +++ b/Sources/NIOPosix/BaseSocketChannel.swift @@ -387,7 +387,7 @@ class BaseSocketChannel: SelectableChannel, Chan /// Read data from the underlying socket and dispatch it to the `ChannelPipeline` /// - /// - returns: `true` if any data was read, `false` otherwise. + /// - Returns: `true` if any data was read, `false` otherwise. @discardableResult func readFromSocket() throws -> ReadResult { fatalError("this must be overridden by sub class") } @@ -426,18 +426,18 @@ class BaseSocketChannel: SelectableChannel, Chan /// Begin connection of the underlying socket. /// - /// - parameters: - /// - to: The `SocketAddress` to connect to. - /// - returns: `true` if the socket connected synchronously, `false` otherwise. + /// - Parameters: + /// - to: The `SocketAddress` to connect to. + /// - Returns: `true` if the socket connected synchronously, `false` otherwise. func connectSocket(to address: SocketAddress) throws -> Bool { fatalError("this must be overridden by sub class") } /// Begin connection of the underlying socket. /// - /// - parameters: - /// - to: The `VsockAddress` to connect to. - /// - returns: `true` if the socket connected synchronously, `false` otherwise. + /// - Parameters: + /// - to: The `VsockAddress` to connect to. + /// - Returns: `true` if the socket connected synchronously, `false` otherwise. func connectSocket(to address: VsockAddress) throws -> Bool { fatalError("this must be overridden by sub class") } @@ -449,9 +449,9 @@ class BaseSocketChannel: SelectableChannel, Chan /// Begin connection of the underlying socket. /// - /// - parameters: - /// - to: The target to connect to. - /// - returns: `true` if the socket connected synchronously, `false` otherwise. + /// - Parameters: + /// - to: The target to connect to. + /// - Returns: `true` if the socket connected synchronously, `false` otherwise. final func connectSocket(to target: ConnectTarget) throws -> Bool { switch target { case .socketAddress(let address): @@ -542,7 +542,7 @@ class BaseSocketChannel: SelectableChannel, Chan /// This method can be called re-entrantly but it will return immediately because the first call is responsible /// for sending all flushed writes, even the ones that are accumulated whilst `flushNow()` is running. /// - /// - returns: If this socket should be registered for write notifications. Ie. `IONotificationState.register` if + /// - Returns: If this socket should be registered for write notifications. Ie. `IONotificationState.register` if /// _not_ all data could be written, so notifications are necessary; and `IONotificationState.unregister` /// if everything was written and we don't need to be notified about writability at the moment. func flushNow() -> IONotificationState { @@ -696,7 +696,7 @@ class BaseSocketChannel: SelectableChannel, Chan /// Triggers a `ChannelPipeline.read()` if `autoRead` is enabled.` /// - /// - returns: `true` if `readPending` is `true`, `false` otherwise. + /// - Returns: `true` if `readPending` is `true`, `false` otherwise. @discardableResult func readIfNeeded0() -> Bool { self.eventLoop.assertInEventLoop() if !self.lifecycleManager.isActive { @@ -843,7 +843,7 @@ class BaseSocketChannel: SelectableChannel, Chan /// So unless either the deregistration or the close itself fails, `promise` will be succeeded regardless of /// `error`. `error` is used to fail outstanding writes (if any) and the `connectPromise` if set. /// - /// - parameters: + /// - Parameters: /// - error: The error to fail the outstanding (if any) writes/connect with. /// - mode: The close mode, must be `.all` for `BaseSocketChannel` /// - promise: The promise that gets notified about the result of the deregistration/close operations. @@ -1202,9 +1202,9 @@ class BaseSocketChannel: SelectableChannel, Chan /// Returns `true` if the `Channel` should be closed as result of the given `Error` which happened during `readFromSocket`. /// - /// - parameters: - /// - err: The `Error` which was thrown by `readFromSocket`. - /// - returns: `true` if the `Channel` should be closed, `false` otherwise. + /// - Parameters: + /// - err: The `Error` which was thrown by `readFromSocket`. + /// - Returns: `true` if the `Channel` should be closed, `false` otherwise. func shouldCloseOnReadError(_ err: Error) -> Bool { true } diff --git a/Sources/NIOPosix/Bootstrap.swift b/Sources/NIOPosix/Bootstrap.swift index f37abb37c5..c48043651b 100644 --- a/Sources/NIOPosix/Bootstrap.swift +++ b/Sources/NIOPosix/Bootstrap.swift @@ -94,8 +94,8 @@ public final class ServerBootstrap { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:childGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup`s are compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. + /// - Parameters: + /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. public convenience init(group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { preconditionFailure( @@ -113,9 +113,9 @@ public final class ServerBootstrap { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:childGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup`s are compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. - /// - childGroup: The `EventLoopGroup` to run the accepted `SocketChannel`s on. + /// - Parameters: + /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. + /// - childGroup: The `EventLoopGroup` to run the accepted `SocketChannel`s on. public convenience init(group: EventLoopGroup, childGroup: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) && NIOOnSocketsBootstraps.isCompatible(group: childGroup) @@ -133,9 +133,9 @@ public final class ServerBootstrap { /// Create a `ServerBootstrap` on the `EventLoopGroup` `group` which accepts `Channel`s on `childGroup`, validating /// that the `EventLoopGroup`s are compatible with `ServerBootstrap`. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. - /// - childGroup: The `EventLoopGroup` to run the accepted `SocketChannel`s on. If `nil`, `group` is used. + /// - Parameters: + /// - group: The `EventLoopGroup` to use for the `bind` of the `ServerSocketChannel` and to accept new `SocketChannel`s with. + /// - childGroup: The `EventLoopGroup` to run the accepted `SocketChannel`s on. If `nil`, `group` is used. public init?(validatingGroup group: EventLoopGroup, childGroup: EventLoopGroup? = nil) { let childGroup = childGroup ?? group guard @@ -159,10 +159,10 @@ public final class ServerBootstrap { /// /// The `ServerSocketChannel` uses the accepted `Channel`s as inbound messages. /// - /// - note: To set the initializer for the accepted `SocketChannel`s, look at `ServerBootstrap.childChannelInitializer`. + /// - Note: To set the initializer for the accepted `SocketChannel`s, look at `ServerBootstrap.childChannelInitializer`. /// - /// - parameters: - /// - initializer: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - initializer: A closure that initializes the provided `Channel`. @preconcurrency public func serverChannelInitializer(_ initializer: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { @@ -182,8 +182,8 @@ public final class ServerBootstrap { /// /// The accepted `Channel` will operate on `ByteBuffer` as inbound and `IOData` as outbound messages. /// - /// - parameters: - /// - initializer: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - initializer: A closure that initializes the provided `Channel`. @preconcurrency public func childChannelInitializer(_ initializer: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { self.childChannelInit = initializer @@ -192,11 +192,11 @@ public final class ServerBootstrap { /// Specifies a `ChannelOption` to be applied to the `ServerSocketChannel`. /// - /// - note: To specify options for the accepted `SocketChannel`s, look at `ServerBootstrap.childChannelOption`. + /// - Note: To specify options for the accepted `SocketChannel`s, look at `ServerBootstrap.childChannelOption`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func serverChannelOption(_ option: Option, value: Option.Value) -> Self { self._serverChannelOptions.append(key: option, value: value) @@ -205,9 +205,9 @@ public final class ServerBootstrap { /// Specifies a `ChannelOption` to be applied to the accepted `SocketChannel`s. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func childChannelOption(_ option: Option, value: Option.Value) -> Self { self._childChannelOptions.append(key: option, value: value) @@ -216,8 +216,8 @@ public final class ServerBootstrap { /// Specifies a timeout to apply to a bind attempt. Currently unsupported. /// - /// - parameters: - /// - timeout: The timeout that will apply to the bind attempt. + /// - Parameters: + /// - timeout: The timeout that will apply to the bind attempt. public func bindTimeout(_ timeout: TimeAmount) -> Self { self } @@ -232,8 +232,8 @@ public final class ServerBootstrap { /// > had been disabled. This is a temporary workaround for a Linux kernel /// > limitation. /// - /// - parameters: - /// - value: Whether to enable MPTCP or not. + /// - Parameters: + /// - value: Whether to enable MPTCP or not. public func enableMPTCP(_ value: Bool) -> Self { self.enableMPTCP = value @@ -248,9 +248,9 @@ public final class ServerBootstrap { /// Bind the `ServerSocketChannel` to `host` and `port`. /// - /// - parameters: - /// - host: The host to bind on. - /// - port: The port to bind on. + /// - Parameters: + /// - host: The host to bind on. + /// - port: The port to bind on. public func bind(host: String, port: Int) -> EventLoopFuture { bind0 { try SocketAddress.makeAddressResolvingHost(host, port: port) @@ -259,16 +259,16 @@ public final class ServerBootstrap { /// Bind the `ServerSocketChannel` to `address`. /// - /// - parameters: - /// - address: The `SocketAddress` to bind on. + /// - Parameters: + /// - address: The `SocketAddress` to bind on. public func bind(to address: SocketAddress) -> EventLoopFuture { bind0 { address } } /// Bind the `ServerSocketChannel` to a UNIX Domain Socket. /// - /// - parameters: - /// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system. + /// - Parameters: + /// - unixDomainSocketPath: The _Unix domain socket_ path to bind to. `unixDomainSocketPath` must not exist, it will be created by the system. public func bind(unixDomainSocketPath: String) -> EventLoopFuture { bind0 { try SocketAddress(unixDomainSocketPath: unixDomainSocketPath) @@ -277,10 +277,10 @@ public final class ServerBootstrap { /// Bind the `ServerSocketChannel` to a UNIX Domain Socket. /// - /// - parameters: - /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. The`unixDomainSocketPath` must not exist, + /// - Parameters: + /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. The`unixDomainSocketPath` must not exist, /// unless `cleanupExistingSocketFile`is set to `true`. - /// - cleanupExistingSocketFile: Whether to cleanup an existing socket file at `unixDomainSocketPath`. + /// - cleanupExistingSocketFile: Whether to cleanup an existing socket file at `unixDomainSocketPath`. public func bind(unixDomainSocketPath: String, cleanupExistingSocketFile: Bool) -> EventLoopFuture { if cleanupExistingSocketFile { do { @@ -295,7 +295,7 @@ public final class ServerBootstrap { /// Bind the `ServerSocketChannel` to a VSOCK socket. /// - /// - parameters: + /// - Parameters: /// - vsockAddress: The VSOCK socket address to bind on. public func bind(to vsockAddress: VsockAddress) -> EventLoopFuture { func makeChannel( @@ -325,8 +325,8 @@ public final class ServerBootstrap { #if !os(Windows) /// Use the existing bound socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound stream socket. + /// - Parameters: + /// - descriptor: The _Unix file descriptor_ representing the bound stream socket. @available(*, deprecated, renamed: "withBoundSocket(_:)") public func withBoundSocket(descriptor: CInt) -> EventLoopFuture { withBoundSocket(descriptor) @@ -335,8 +335,8 @@ public final class ServerBootstrap { /// Use the existing bound socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound stream socket. + /// - Parameters: + /// - socket: The _Unix file descriptor_ representing the bound stream socket. public func withBoundSocket(_ socket: NIOBSDSocket.Handle) -> EventLoopFuture { func makeChannel( _ eventLoop: SelectableEventLoop, @@ -515,7 +515,7 @@ extension ServerBootstrap { /// - host: The host to bind on. /// - port: The port to bind on. /// - serverBackPressureStrategy: The back pressure strategy used by the server socket channel. - /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` + /// - childChannelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -539,7 +539,7 @@ extension ServerBootstrap { /// - Parameters: /// - address: The `SocketAddress` to bind on. /// - serverBackPressureStrategy: The back pressure strategy used by the server socket channel. - /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` + /// - childChannelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -574,7 +574,7 @@ extension ServerBootstrap { /// unless `cleanupExistingSocketFile`is set to `true`. /// - cleanupExistingSocketFile: Whether to cleanup an existing socket file at `unixDomainSocketPath`. /// - serverBackPressureStrategy: The back pressure strategy used by the server socket channel. - /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` + /// - childChannelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -602,7 +602,7 @@ extension ServerBootstrap { /// - Parameters: /// - vsockAddress: The VSOCK socket address to bind on. /// - serverBackPressureStrategy: The back pressure strategy used by the server socket channel. - /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` + /// - childChannelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -644,8 +644,9 @@ extension ServerBootstrap { /// /// - Parameters: /// - socket: The _Unix file descriptor_ representing the bound stream socket. + /// - cleanupExistingSocketFile: Unused. /// - serverBackPressureStrategy: The back pressure strategy used by the server socket channel. - /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` + /// - childChannelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -821,8 +822,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup` is compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public convenience init(group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { preconditionFailure( @@ -835,8 +836,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Create a `ClientBootstrap` on the `EventLoopGroup` `group`, validating that `group` is compatible. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public init?(validatingGroup group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { return nil @@ -866,8 +867,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// might be called multiple times and it's important not to share stateful `ChannelHandler`s in more /// than one `Channel`. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. @preconcurrency public func channelInitializer(_ handler: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { self._channelInitializer = handler @@ -889,9 +890,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specifies a `ChannelOption` to be applied to the `SocketChannel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func channelOption(_ option: Option, value: Option.Value) -> Self { self._channelOptions.append(key: option, value: value) @@ -900,8 +901,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specifies a timeout to apply to a connection attempt. /// - /// - parameters: - /// - timeout: The timeout that will apply to the connection attempt. + /// - Parameters: + /// - timeout: The timeout that will apply to the connection attempt. public func connectTimeout(_ timeout: TimeAmount) -> Self { self.connectTimeout = timeout return self @@ -909,8 +910,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specifies the `Resolver` to use or `nil` if the default should be used. /// - /// - parameters: - /// - resolver: The resolver that will be used during the connection attempt. + /// - Parameters: + /// - resolver: The resolver that will be used during the connection attempt. public func resolver(_ resolver: Resolver?) -> Self { self.resolver = resolver return self @@ -926,8 +927,8 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// > had been disabled. This is a temporary workaround for a Linux kernel /// > limitation. /// - /// - parameters: - /// - value: Whether to enable MPTCP or not. + /// - Parameters: + /// - value: Whether to enable MPTCP or not. public func enableMPTCP(_ value: Bool) -> Self { self.enableMPTCP = value @@ -944,10 +945,10 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// /// Using `bind` is not necessary unless you need the local address to be bound to a specific address. /// - /// - note: Using `bind` will disable Happy Eyeballs on this `Channel`. + /// - Note: Using `bind` will disable Happy Eyeballs on this `Channel`. /// - /// - parameters: - /// - address: The `SocketAddress` to bind on. + /// - Parameters: + /// - address: The `SocketAddress` to bind on. public func bind(to address: SocketAddress) -> ClientBootstrap { self.bindTarget = address return self @@ -966,10 +967,10 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specify the `host` and `port` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - host: The host to connect to. - /// - port: The port to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - host: The host to connect to. + /// - port: The port to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(host: String, port: Int) -> EventLoopFuture { let loop = self.group.next() let resolver = @@ -1018,9 +1019,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specify the `address` to connect to for the TCP `Channel` that will be established. /// - /// - parameters: - /// - address: The address to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - address: The address to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(to address: SocketAddress) -> EventLoopFuture { self.initializeAndRegisterNewChannel( eventLoop: self.group.next(), @@ -1032,9 +1033,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specify the `unixDomainSocket` path to connect to for the UDS `Channel` that will be established. /// - /// - parameters: - /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. - /// - returns: An `EventLoopFuture` to deliver the `Channel` when connected. + /// - Parameters: + /// - unixDomainSocketPath: The _Unix domain socket_ path to connect to. + /// - Returns: An `EventLoopFuture` to deliver the `Channel` when connected. public func connect(unixDomainSocketPath: String) -> EventLoopFuture { do { let address = try SocketAddress(unixDomainSocketPath: unixDomainSocketPath) @@ -1046,9 +1047,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Specify the VSOCK address to connect to for the `Channel`. /// - /// - parameters: - /// - address: The VSOCK address to connect to. - /// - returns: An `EventLoopFuture` for when the `Channel` is connected. + /// - Parameters: + /// - address: The VSOCK address to connect to. + /// - Returns: An `EventLoopFuture` for when the `Channel` is connected. public func connect(to address: VsockAddress) -> EventLoopFuture { let connectTimeout = self.connectTimeout return self.initializeAndRegisterNewChannel( @@ -1073,9 +1074,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { #if !os(Windows) /// Use the existing connected socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the connected stream socket. - /// - returns: an `EventLoopFuture` to deliver the `Channel`. + /// - Parameters: + /// - descriptor: The _Unix file descriptor_ representing the connected stream socket. + /// - Returns: an `EventLoopFuture` to deliver the `Channel`. @available(*, deprecated, renamed: "withConnectedSocket(_:)") public func withConnectedSocket(descriptor: CInt) -> EventLoopFuture { self.withConnectedSocket(descriptor) @@ -1084,9 +1085,9 @@ public final class ClientBootstrap: NIOClientTCPBootstrapProtocol { /// Use the existing connected socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the connected stream socket. - /// - returns: an `EventLoopFuture` to deliver the `Channel`. + /// - Parameters: + /// - socket: The _Unix file descriptor_ representing the connected stream socket. + /// - Returns: an `EventLoopFuture` to deliver the `Channel`. public func withConnectedSocket(_ socket: NIOBSDSocket.Handle) -> EventLoopFuture { let eventLoop = group.next() let channelInitializer = self.channelInitializer @@ -1288,7 +1289,7 @@ extension ClientBootstrap { /// Use the existing connected socket file descriptor. /// /// - Parameters: - /// - descriptor: The _Unix file descriptor_ representing the connected stream socket. + /// - socket: The _Unix file descriptor_ representing the connected stream socket. /// - channelInitializer: A closure to initialize the channel. The return value of this closure is returned from the `connect` /// method. /// - Returns: The result of the channel initializer. @@ -1495,8 +1496,8 @@ public final class DatagramBootstrap { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup` is compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public convenience init(group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { preconditionFailure( @@ -1509,8 +1510,8 @@ public final class DatagramBootstrap { /// Create a `DatagramBootstrap` on the `EventLoopGroup` `group`, validating that `group` is compatible. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public init?(validatingGroup group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { return nil @@ -1523,8 +1524,8 @@ public final class DatagramBootstrap { /// Initialize the bound `DatagramChannel` with `initializer`. The most common task in initializer is to add /// `ChannelHandler`s to the `ChannelPipeline`. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. @preconcurrency public func channelInitializer(_ handler: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { self.channelInitializer = handler @@ -1533,9 +1534,9 @@ public final class DatagramBootstrap { /// Specifies a `ChannelOption` to be applied to the `DatagramChannel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func channelOption(_ option: Option, value: Option.Value) -> Self { self._channelOptions.append(key: option, value: value) @@ -1550,8 +1551,8 @@ public final class DatagramBootstrap { #if !os(Windows) /// Use the existing bound socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound datagram socket. + /// - Parameters: + /// - descriptor: The _Unix file descriptor_ representing the bound datagram socket. @available(*, deprecated, renamed: "withBoundSocket(_:)") public func withBoundSocket(descriptor: CInt) -> EventLoopFuture { self.withBoundSocket(descriptor) @@ -1560,8 +1561,8 @@ public final class DatagramBootstrap { /// Use the existing bound socket file descriptor. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound datagram socket. + /// - Parameters: + /// - socket: The _Unix file descriptor_ representing the bound datagram socket. public func withBoundSocket(_ socket: NIOBSDSocket.Handle) -> EventLoopFuture { func makeChannel(_ eventLoop: SelectableEventLoop) throws -> DatagramChannel { try DatagramChannel(eventLoop: eventLoop, socket: socket) @@ -1575,9 +1576,9 @@ public final class DatagramBootstrap { /// Bind the `DatagramChannel` to `host` and `port`. /// - /// - parameters: - /// - host: The host to bind on. - /// - port: The port to bind on. + /// - Parameters: + /// - host: The host to bind on. + /// - port: The port to bind on. public func bind(host: String, port: Int) -> EventLoopFuture { bind0 { try SocketAddress.makeAddressResolvingHost(host, port: port) @@ -1586,16 +1587,16 @@ public final class DatagramBootstrap { /// Bind the `DatagramChannel` to `address`. /// - /// - parameters: - /// - address: The `SocketAddress` to bind on. + /// - Parameters: + /// - address: The `SocketAddress` to bind on. public func bind(to address: SocketAddress) -> EventLoopFuture { bind0 { address } } /// Bind the `DatagramChannel` to a UNIX Domain Socket. /// - /// - parameters: - /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. `path` must not exist, it will be created by the system. + /// - Parameters: + /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. `path` must not exist, it will be created by the system. public func bind(unixDomainSocketPath: String) -> EventLoopFuture { bind0 { try SocketAddress(unixDomainSocketPath: unixDomainSocketPath) @@ -1604,10 +1605,10 @@ public final class DatagramBootstrap { /// Bind the `DatagramChannel` to a UNIX Domain Socket. /// - /// - parameters: - /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. The`unixDomainSocketPath` must not exist, + /// - Parameters: + /// - unixDomainSocketPath: The path of the UNIX Domain Socket to bind on. The`unixDomainSocketPath` must not exist, /// unless `cleanupExistingSocketFile`is set to `true`. - /// - cleanupExistingSocketFile: Whether to cleanup an existing socket file at `unixDomainSocketPath`. + /// - cleanupExistingSocketFile: Whether to cleanup an existing socket file at `unixDomainSocketPath`. public func bind(unixDomainSocketPath: String, cleanupExistingSocketFile: Bool) -> EventLoopFuture { if cleanupExistingSocketFile { do { @@ -1644,9 +1645,9 @@ public final class DatagramBootstrap { /// Connect the `DatagramChannel` to `host` and `port`. /// - /// - parameters: - /// - host: The host to connect to. - /// - port: The port to connect to. + /// - Parameters: + /// - host: The host to connect to. + /// - port: The port to connect to. public func connect(host: String, port: Int) -> EventLoopFuture { connect0 { try SocketAddress.makeAddressResolvingHost(host, port: port) @@ -1655,16 +1656,16 @@ public final class DatagramBootstrap { /// Connect the `DatagramChannel` to `address`. /// - /// - parameters: - /// - address: The `SocketAddress` to connect to. + /// - Parameters: + /// - address: The `SocketAddress` to connect to. public func connect(to address: SocketAddress) -> EventLoopFuture { connect0 { address } } /// Connect the `DatagramChannel` to a UNIX Domain Socket. /// - /// - parameters: - /// - unixDomainSocketPath: The path of the UNIX Domain Socket to connect to. `path` must not exist, it will be created by the system. + /// - Parameters: + /// - unixDomainSocketPath: The path of the UNIX Domain Socket to connect to. `path` must not exist, it will be created by the system. public func connect(unixDomainSocketPath: String) -> EventLoopFuture { connect0 { try SocketAddress(unixDomainSocketPath: unixDomainSocketPath) @@ -2054,8 +2055,8 @@ public final class NIOPipeBootstrap { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup`s are compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public convenience init(group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { preconditionFailure( @@ -2068,8 +2069,8 @@ public final class NIOPipeBootstrap { /// Create a `NIOPipeBootstrap` on the `EventLoopGroup` `group`, validating that `group` is compatible. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public init?(validatingGroup group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { return nil @@ -2099,8 +2100,8 @@ public final class NIOPipeBootstrap { /// The connected `Channel` will operate on `ByteBuffer` as inbound and outbound messages. Please note that /// `IOData.fileRegion` is _not_ supported for `PipeChannel`s because `sendfile` only works on sockets. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. @preconcurrency public func channelInitializer(_ handler: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { self.channelInitializer = handler @@ -2109,9 +2110,9 @@ public final class NIOPipeBootstrap { /// Specifies a `ChannelOption` to be applied to the `PipeChannel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func channelOption(_ option: Option, value: Option.Value) -> Self { self._channelOptions.append(key: option, value: value) diff --git a/Sources/NIOPosix/ControlMessage.swift b/Sources/NIOPosix/ControlMessage.swift index 96fe3ea6fc..79cf861e58 100644 --- a/Sources/NIOPosix/ControlMessage.swift +++ b/Sources/NIOPosix/ControlMessage.swift @@ -29,10 +29,10 @@ struct UnsafeControlMessageStorage: Collection { private let deallocateBuffer: Bool /// Initialise which includes allocating memory - /// parameter: - /// - bytesPerMessage: How many bytes have been allocated for each supported message. - /// - buffer: The memory allocated to use for control messages. - /// - deallocateBuffer: buffer owning indicator + /// - Parameters: + /// - bytesPerMessage: How many bytes have been allocated for each supported message. + /// - buffer: The memory allocated to use for control messages. + /// - deallocateBuffer: buffer owning indicator private init(bytesPerMessage: Int, buffer: UnsafeMutableRawBufferPointer, deallocateBuffer: Bool) { self.bytesPerMessage = bytesPerMessage self.buffer = buffer @@ -43,7 +43,7 @@ struct UnsafeControlMessageStorage: Collection { static var bytesPerMessage: Int { NIOBSDSocketControlMessage.space(payloadSize: MemoryLayout.stride) * 4 } /// Allocate new memory - Caller must call `deallocate` when no longer required. - /// parameter: + /// - Parameters: /// - msghdrCount: How many `msghdr` structures will be fed from this buffer - we assume 4 Int32 cmsgs for each. static func allocate(msghdrCount: Int) -> UnsafeControlMessageStorage { let bytesPerMessage = Self.bytesPerMessage @@ -55,9 +55,9 @@ struct UnsafeControlMessageStorage: Collection { } /// Create an instance not owning the buffer - /// parameter: - /// - bytesPerMessage: How many bytes have been allocated for each supported message. - /// - buffer: The memory allocated to use for control messages. + /// - Parameters: + /// - bytesPerMessage: How many bytes have been allocated for each supported message. + /// - buffer: The memory allocated to use for control messages. static func makeNotOwning( bytesPerMessage: Int, buffer: UnsafeMutableRawBufferPointer @@ -350,8 +350,8 @@ struct UnsafeOutboundControlBytes { extension UnsafeOutboundControlBytes { /// Add a message describing the explicit congestion state if requested in metadata and valid for this protocol. /// Parameters: - /// - metadata: Metadata from the addressed envelope which will describe any desired state. - /// - protocolFamily: The type of protocol to encode for. + /// - metadata: Metadata from the addressed envelope which will describe any desired state. + /// - protocolFamily: The type of protocol to encode for. internal mutating func appendExplicitCongestionState( metadata: AddressedEnvelope.Metadata?, protocolFamily: NIOBSDSocket.ProtocolFamily? diff --git a/Sources/NIOPosix/DatagramVectorReadManager.swift b/Sources/NIOPosix/DatagramVectorReadManager.swift index 07f1907dab..2d4987a9d6 100644 --- a/Sources/NIOPosix/DatagramVectorReadManager.swift +++ b/Sources/NIOPosix/DatagramVectorReadManager.swift @@ -90,10 +90,10 @@ struct DatagramVectorReadManager { /// obtain a pointer to the entire buffer storage. This is because they assume they own the entire /// buffer. /// - /// - parameters: - /// - socket: The underlying socket from which to read. - /// - buffer: The single large buffer into which reads will be written. - /// - parseControlMessages: Should control messages be reported up using metadata. + /// - Parameters: + /// - socket: The underlying socket from which to read. + /// - buffer: The single large buffer into which reads will be written. + /// - parseControlMessages: Should control messages be reported up using metadata. func readFromSocket( socket: Socket, buffer: inout ByteBuffer, @@ -216,8 +216,8 @@ struct DatagramVectorReadManager { extension DatagramVectorReadManager { /// Allocates and initializes a new DatagramVectorReadManager. /// - /// - parameters: - /// - messageCount: The number of vector reads to support initially. + /// - Parameters: + /// - messageCount: The number of vector reads to support initially. static func allocate(messageCount: Int) -> DatagramVectorReadManager { let messageVector = UnsafeMutableBufferPointer.allocateAndInitialize( repeating: MMsgHdr(msg_hdr: msghdr(), msg_len: 0), diff --git a/Sources/NIOPosix/GetaddrinfoResolver.swift b/Sources/NIOPosix/GetaddrinfoResolver.swift index fc07d59a52..7a17589fb0 100644 --- a/Sources/NIOPosix/GetaddrinfoResolver.swift +++ b/Sources/NIOPosix/GetaddrinfoResolver.swift @@ -58,10 +58,10 @@ internal class GetaddrinfoResolver: Resolver { /// Create a new resolver. /// - /// - parameters: - /// - loop: The `EventLoop` whose thread this resolver will block. - /// - aiSocktype: The sock type to use as hint when calling getaddrinfo. - /// - aiProtocol: the protocol to use as hint when calling getaddrinfo. + /// - Parameters: + /// - loop: The `EventLoop` whose thread this resolver will block. + /// - aiSocktype: The sock type to use as hint when calling getaddrinfo. + /// - aiProtocol: the protocol to use as hint when calling getaddrinfo. init( loop: EventLoop, aiSocktype: NIOBSDSocket.SocketType, @@ -79,10 +79,10 @@ internal class GetaddrinfoResolver: Resolver { /// That means this just returns the future for the A results, which in practice will always have been /// satisfied by the time this function is called. /// - /// - parameters: - /// - host: The hostname to do an A lookup on. - /// - port: The port we'll be connecting to. - /// - returns: An `EventLoopFuture` that fires with the result of the lookup. + /// - Parameters: + /// - host: The hostname to do an A lookup on. + /// - port: The port we'll be connecting to. + /// - Returns: An `EventLoopFuture` that fires with the result of the lookup. func initiateAQuery(host: String, port: Int) -> EventLoopFuture<[SocketAddress]> { v4Future.futureResult } @@ -92,10 +92,10 @@ internal class GetaddrinfoResolver: Resolver { /// Due to the nature of `getaddrinfo`, we only actually call the function once, in this function. /// That means this function call actually blocks: sorry! /// - /// - parameters: - /// - host: The hostname to do an AAAA lookup on. - /// - port: The port we'll be connecting to. - /// - returns: An `EventLoopFuture` that fires with the result of the lookup. + /// - Parameters: + /// - host: The hostname to do an AAAA lookup on. + /// - port: The port we'll be connecting to. + /// - Returns: An `EventLoopFuture` that fires with the result of the lookup. func initiateAAAAQuery(host: String, port: Int) -> EventLoopFuture<[SocketAddress]> { self.offloadQueue().async { self.resolveBlocking(host: host, port: port) @@ -129,9 +129,9 @@ internal class GetaddrinfoResolver: Resolver { /// Perform the DNS queries and record the result. /// - /// - parameters: - /// - host: The hostname to do the DNS queries on. - /// - port: The port we'll be connecting to. + /// - Parameters: + /// - host: The hostname to do the DNS queries on. + /// - port: The port we'll be connecting to. private func resolveBlocking(host: String, port: Int) { #if os(Windows) host.withCString(encodedAs: UTF16.self) { wszHost in @@ -179,9 +179,9 @@ internal class GetaddrinfoResolver: Resolver { /// Parses the DNS results from the `addrinfo` linked list. /// - /// - parameters: - /// - info: The pointer to the first of the `addrinfo` structures in the list. - /// - host: The hostname we resolved. + /// - Parameters: + /// - info: The pointer to the first of the `addrinfo` structures in the list. + /// - host: The hostname we resolved. #if os(Windows) internal typealias CAddrInfo = ADDRINFOW #else @@ -220,8 +220,8 @@ internal class GetaddrinfoResolver: Resolver { /// Record an error and fail the lookup process. /// - /// - parameters: - /// - error: The error encountered during lookup. + /// - Parameters: + /// - error: The error encountered during lookup. private func fail(_ error: Error) { self.v6Future.fail(error) self.v4Future.fail(error) diff --git a/Sources/NIOPosix/HappyEyeballs.swift b/Sources/NIOPosix/HappyEyeballs.swift index ffc1a06139..015a8b4af6 100644 --- a/Sources/NIOPosix/HappyEyeballs.swift +++ b/Sources/NIOPosix/HappyEyeballs.swift @@ -367,8 +367,8 @@ internal final class HappyEyeballsConnector { /// Spin the state machine. /// - /// - parameters: - /// - input: The input to the state machine. + /// - Parameters: + /// - input: The input to the state machine. private func processInput(_ input: ConnectorInput) { switch (state, input) { // Only one valid transition from idle: to start resolving. @@ -584,8 +584,8 @@ internal final class HappyEyeballsConnector { /// Called to connect to a given target. /// - /// - parameters: - /// - target: The address to connect to. + /// - Parameters: + /// - target: The address to connect to. private func connectToTarget(_ target: SocketAddress) { let channelFuture = channelBuilderCallback(self.loop, target.protocol) pendingConnections.append(channelFuture) diff --git a/Sources/NIOPosix/LinuxCPUSet.swift b/Sources/NIOPosix/LinuxCPUSet.swift index ffa3c49672..6e4af51c42 100644 --- a/Sources/NIOPosix/LinuxCPUSet.swift +++ b/Sources/NIOPosix/LinuxCPUSet.swift @@ -23,7 +23,7 @@ struct LinuxCPUSet { /// Create a new instance /// /// - arguments: - /// - cpuIds: The `Set` of CPU ids. It must be non-empty and can not contain invalid ids. + /// - cpuIds: The `Set` of CPU ids. It must be non-empty and can not contain invalid ids. init(cpuIds: Set) { precondition(!cpuIds.isEmpty) self.cpuIds = cpuIds @@ -32,7 +32,7 @@ struct LinuxCPUSet { /// Create a new instance /// /// - arguments: - /// - cpuId: The CPU id. + /// - cpuId: The CPU id. init(_ cpuId: Int) { let ids: Set = [cpuId] self.init(cpuIds: ids) @@ -87,7 +87,7 @@ extension MultiThreadedEventLoopGroup { /// Create a new `MultiThreadedEventLoopGroup` that create as many `NIOThread`s as `pinnedCPUIds`. Each `NIOThread` will be pinned to the CPU with the id. /// /// - arguments: - /// - pinnedCPUIds: The CPU ids to apply to the `NIOThread`s. + /// - pinnedCPUIds: The CPU ids to apply to the `NIOThread`s. convenience init(pinnedCPUIds: [Int]) { let initializers: [ThreadInitializer] = pinnedCPUIds.map { id in // This will also take care of validation of the provided id. diff --git a/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift b/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift index 6e20a9a98c..c09f9fe8d3 100644 --- a/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift +++ b/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift @@ -48,7 +48,7 @@ typealias ThreadInitializer = (NIOThread) -> Void /// all run their own `EventLoop`. Those threads will not be shut down until `shutdownGracefully` or /// `syncShutdownGracefully` is called. /// -/// - note: It's good style to call `MultiThreadedEventLoopGroup.shutdownGracefully` or +/// - Note: It's good style to call `MultiThreadedEventLoopGroup.shutdownGracefully` or /// `MultiThreadedEventLoopGroup.syncShutdownGracefully` when you no longer need this `EventLoopGroup`. In /// many cases that is just before your program exits. /// - warning: Unit tests often spawn one `MultiThreadedEventLoopGroup` per unit test to force isolation between the @@ -140,13 +140,13 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Creates a `MultiThreadedEventLoopGroup` instance which uses `numberOfThreads`. /// - /// - note: Don't forget to call `shutdownGracefully` or `syncShutdownGracefully` when you no longer need this + /// - Note: Don't forget to call `shutdownGracefully` or `syncShutdownGracefully` when you no longer need this /// `EventLoopGroup`. If you forget to shut the `EventLoopGroup` down you will leak `numberOfThreads` /// (kernel) threads which are costly resources. This is especially important in unit tests where one /// `MultiThreadedEventLoopGroup` is started per test case. /// /// - arguments: - /// - numberOfThreads: The number of `Threads` to use. + /// - numberOfThreads: The number of `Threads` to use. public convenience init(numberOfThreads: Int) { self.init( numberOfThreads: numberOfThreads, @@ -158,7 +158,7 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Creates a `MultiThreadedEventLoopGroup` instance which uses `numberOfThreads`. /// - /// - note: Don't forget to call `shutdownGracefully` or `syncShutdownGracefully` when you no longer need this + /// - Note: Don't forget to call `shutdownGracefully` or `syncShutdownGracefully` when you no longer need this /// `EventLoopGroup`. If you forget to shut the `EventLoopGroup` down you will leak `numberOfThreads` /// (kernel) threads which are costly resources. This is especially important in unit tests where one /// `MultiThreadedEventLoopGroup` is started per test case. @@ -257,7 +257,7 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Creates a `MultiThreadedEventLoopGroup` instance which uses the given `ThreadInitializer`s. One `NIOThread` per `ThreadInitializer` is created and used. /// /// - arguments: - /// - threadInitializers: The `ThreadInitializer`s to use. + /// - threadInitializers: The `ThreadInitializer`s to use. internal init( threadInitializers: [ThreadInitializer], canBeShutDown: Bool, @@ -292,7 +292,7 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Returns the `EventLoop` for the calling thread. /// - /// - returns: The current `EventLoop` for the calling thread or `nil` if none is assigned to the thread. + /// - Returns: The current `EventLoop` for the calling thread or `nil` if none is assigned to the thread. public static var currentEventLoop: EventLoop? { self.currentSelectableEventLoop } @@ -303,7 +303,7 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Returns an `EventLoopIterator` over the `EventLoop`s in this `MultiThreadedEventLoopGroup`. /// - /// - returns: `EventLoopIterator` + /// - Returns: `EventLoopIterator` public func makeIterator() -> EventLoopIterator { EventLoopIterator(self.eventLoops) } @@ -312,14 +312,14 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// /// `MultiThreadedEventLoopGroup` uses _round robin_ across all its `EventLoop`s to select the next one. /// - /// - returns: The next `EventLoop` to use. + /// - Returns: The next `EventLoop` to use. public func next() -> EventLoop { eventLoops[abs(index.loadThenWrappingIncrement(ordering: .relaxed) % eventLoops.count)] } /// Returns the current `EventLoop` if we are on an `EventLoop` of this `MultiThreadedEventLoopGroup` instance. /// - /// - returns: The `EventLoop`. + /// - Returns: The `EventLoop`. public func any() -> EventLoop { if let loop = Self.currentSelectableEventLoop, // We are on `loop`'s thread, so we may ask for the its parent group. @@ -340,7 +340,7 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// Even though calling `shutdownGracefully` more than once should be avoided, it is safe to do so and execution /// of the `handler` is guaranteed. /// - /// - parameters: + /// - Parameters: /// - queue: The `DispatchQueue` to run `handler` on when the shutdown operation completes. /// - handler: The handler which is called after the shutdown operation completes. The parameter will be `nil` /// on success and contain the `Error` otherwise. @@ -447,8 +447,8 @@ public final class MultiThreadedEventLoopGroup: EventLoopGroup { /// This function will not return until the `EventLoop` has stopped. You can initiate stopping the `EventLoop` by /// calling `eventLoop.shutdownGracefully` which will eventually make this function return. /// - /// - parameters: - /// - callback: Called _on_ the `EventLoop` that the calling thread was converted to, providing you the + /// - Parameters: + /// - callback: Called _on_ the `EventLoop` that the calling thread was converted to, providing you the /// `EventLoop` reference. Just like usually on the `EventLoop`, do not block in `callback`. public static func withCurrentThreadAsEventLoop(_ callback: @escaping (EventLoop) -> Void) { let callingThread = NIOThread.current diff --git a/Sources/NIOPosix/NIOThreadPool.swift b/Sources/NIOPosix/NIOThreadPool.swift index c5817601f6..e60a73812d 100644 --- a/Sources/NIOPosix/NIOThreadPool.swift +++ b/Sources/NIOPosix/NIOThreadPool.swift @@ -44,7 +44,7 @@ public enum NIOThreadPoolError { /// APIs exist. In those cases `NIOThreadPool` can be used but should be /// treated as a last resort. /// -/// - note: The prime example for missing non-blocking APIs is file IO on UNIX. +/// - Note: The prime example for missing non-blocking APIs is file IO on UNIX. /// The OS does not provide a usable and truly non-blocking API but with /// `NonBlockingFileIO` NIO provides a high-level API for file IO that should /// be preferred to running blocking file IO system calls directly on @@ -108,9 +108,9 @@ public final class NIOThreadPool { /// Gracefully shutdown this `NIOThreadPool`. All tasks will be run before shutdown will take place. /// - /// - parameters: - /// - queue: The `DispatchQueue` used to executed the callback - /// - callback: The function to be executed once the shutdown is complete. + /// - Parameters: + /// - queue: The `DispatchQueue` used to executed the callback + /// - callback: The function to be executed once the shutdown is complete. @preconcurrency public func shutdownGracefully(queue: DispatchQueue, _ callback: @escaping @Sendable (Error?) -> Void) { self._shutdownGracefully(queue: queue, callback) @@ -161,10 +161,10 @@ public final class NIOThreadPool { /// Submit a `WorkItem` to process. /// - /// - note: This is a low-level method, in most cases the `runIfActive` method should be used. + /// - Note: This is a low-level method, in most cases the `runIfActive` method should be used. /// - /// - parameters: - /// - body: The `WorkItem` to process by the `NIOThreadPool`. + /// - Parameters: + /// - body: The `WorkItem` to process by the `NIOThreadPool`. @preconcurrency public func submit(_ body: @escaping WorkItem) { self._submit(id: nil, body) @@ -191,7 +191,7 @@ public final class NIOThreadPool { /// Initialize a `NIOThreadPool` thread pool with `numberOfThreads` threads. /// - /// - parameters: + /// - Parameters: /// - numberOfThreads: The number of threads to use for the thread pool. public convenience init(numberOfThreads: Int) { self.init(numberOfThreads: numberOfThreads, canBeStopped: true) @@ -326,10 +326,10 @@ extension NIOThreadPool { /// Runs the submitted closure if the thread pool is still active, otherwise fails the promise. /// The closure will be run on the thread pool so can do blocking work. /// - /// - parameters: - /// - eventLoop: The `EventLoop` the returned `EventLoopFuture` will fire on. - /// - body: The closure which performs some blocking work to be done on the thread pool. - /// - returns: The `EventLoopFuture` of `promise` fulfilled with the result (or error) of the passed closure. + /// - Parameters: + /// - eventLoop: The `EventLoop` the returned `EventLoopFuture` will fire on. + /// - body: The closure which performs some blocking work to be done on the thread pool. + /// - Returns: The `EventLoopFuture` of `promise` fulfilled with the result (or error) of the passed closure. @preconcurrency public func runIfActive(eventLoop: EventLoop, _ body: @escaping @Sendable () throws -> T) -> EventLoopFuture { self._runIfActive(eventLoop: eventLoop, body) @@ -354,9 +354,9 @@ extension NIOThreadPool { /// Runs the submitted closure if the thread pool is still active, otherwise throw an error. /// The closure will be run on the thread pool so can do blocking work. /// - /// - parameters: - /// - body: The closure which performs some blocking work to be done on the thread pool. - /// - returns: result of the passed closure. + /// - Parameters: + /// - body: The closure which performs some blocking work to be done on the thread pool. + /// - Returns: result of the passed closure. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func runIfActive(_ body: @escaping @Sendable () throws -> T) async throws -> T { let workID = self.nextWorkID.loadThenWrappingIncrement(ordering: .relaxed) diff --git a/Sources/NIOPosix/NonBlockingFileIO.swift b/Sources/NIOPosix/NonBlockingFileIO.swift index 2e1c3d565b..e1bb2eb113 100644 --- a/Sources/NIOPosix/NonBlockingFileIO.swift +++ b/Sources/NIOPosix/NonBlockingFileIO.swift @@ -47,7 +47,7 @@ public struct NonBlockingFileIO: Sendable { /// Initialize a ``NonBlockingFileIO`` which uses the `NIOThreadPool`. /// - /// - parameters: + /// - Parameters: /// - threadPool: The `NIOThreadPool` that will be used for all the IO. public init(threadPool: NIOThreadPool) { self.threadPool = threadPool @@ -66,13 +66,13 @@ public struct NonBlockingFileIO: Sendable { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `FileRegion` in multiple threads. /// - /// - parameters: + /// - Parameters: /// - fileRegion: The file region to read. /// - chunkSize: The size of the individual chunks to deliver. /// - allocator: A `ByteBufferAllocator` used to allocate space for the chunks. /// - eventLoop: The `EventLoop` to call `chunkHandler` on. /// - chunkHandler: Called for every chunk read. The next chunk will be read upon successful completion of the returned `EventLoopFuture`. If the returned `EventLoopFuture` fails, the overall operation is aborted. - /// - returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. + /// - Returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. @preconcurrency public func readChunked( fileRegion: FileRegion, @@ -103,20 +103,20 @@ public struct NonBlockingFileIO: Sendable { /// /// The allocation and reading of a subsequent chunk will only be attempted when `chunkHandler` succeeds. /// - /// - note: `readChunked(fileRegion:chunkSize:allocator:eventLoop:chunkHandler:)` should be preferred as it uses + /// - Note: `readChunked(fileRegion:chunkSize:allocator:eventLoop:chunkHandler:)` should be preferred as it uses /// `FileRegion` object instead of raw `NIOFileHandle`s. In case you do want to use raw `NIOFileHandle`s, /// please consider using `readChunked(fileHandle:fromOffset:chunkSize:allocator:eventLoop:chunkHandler:)` /// because it doesn't use the file descriptor's seek pointer (which may be shared with other file /// descriptors and even across processes.) /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read from. /// - byteCount: The number of bytes to read from `fileHandle`. /// - chunkSize: The size of the individual chunks to deliver. /// - allocator: A `ByteBufferAllocator` used to allocate space for the chunks. /// - eventLoop: The `EventLoop` to call `chunkHandler` on. /// - chunkHandler: Called for every chunk read. The next chunk will be read upon successful completion of the returned `EventLoopFuture`. If the returned `EventLoopFuture` fails, the overall operation is aborted. - /// - returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. + /// - Returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. @preconcurrency public func readChunked( fileHandle: NIOFileHandle, @@ -150,17 +150,18 @@ public struct NonBlockingFileIO: Sendable { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `NIOFileHandle` in multiple threads. /// - /// - note: `readChunked(fileRegion:chunkSize:allocator:eventLoop:chunkHandler:)` should be preferred as it uses + /// - Note: `readChunked(fileRegion:chunkSize:allocator:eventLoop:chunkHandler:)` should be preferred as it uses /// `FileRegion` object instead of raw `NIOFileHandle`s. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read from. + /// - fileOffset: The offset into the file at which the read should begin. /// - byteCount: The number of bytes to read from `fileHandle`. /// - chunkSize: The size of the individual chunks to deliver. /// - allocator: A `ByteBufferAllocator` used to allocate space for the chunks. /// - eventLoop: The `EventLoop` to call `chunkHandler` on. /// - chunkHandler: Called for every chunk read. The next chunk will be read upon successful completion of the returned `EventLoopFuture`. If the returned `EventLoopFuture` fails, the overall operation is aborted. - /// - returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. + /// - Returns: An `EventLoopFuture` which is the result of the overall operation. If either the reading of `fileHandle` or `chunkHandler` fails, the `EventLoopFuture` will fail too. If the reading of `fileHandle` as well as `chunkHandler` always succeeded, the `EventLoopFuture` will succeed too. @preconcurrency public func readChunked( fileHandle: NIOFileHandle, @@ -253,14 +254,14 @@ public struct NonBlockingFileIO: Sendable { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `FileRegion` in multiple threads. /// - /// - note: Only use this function for small enough `FileRegion`s as it will need to allocate enough memory to hold `fileRegion.readableBytes` bytes. - /// - note: In most cases you should prefer one of the `readChunked` functions. + /// - Note: Only use this function for small enough `FileRegion`s as it will need to allocate enough memory to hold `fileRegion.readableBytes` bytes. + /// - Note: In most cases you should prefer one of the `readChunked` functions. /// - /// - parameters: + /// - Parameters: /// - fileRegion: The file region to read. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. + /// - Returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. public func read( fileRegion: FileRegion, allocator: ByteBufferAllocator, @@ -281,19 +282,19 @@ public struct NonBlockingFileIO: Sendable { /// The returned `ByteBuffer` will not have less than `byteCount` bytes unless we hit end-of-file in which /// case the `ByteBuffer` will contain the bytes available to read. /// - /// - note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. - /// - note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of + /// - Note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. + /// - Note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of /// raw `NIOFileHandle`s. In case you do want to use raw `NIOFileHandle`s, /// please consider using ``read(fileHandle:fromOffset:byteCount:allocator:eventLoop:)`` /// because it doesn't use the file descriptor's seek pointer (which may be shared with other file /// descriptors and even across processes.) /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read. /// - byteCount: The number of bytes to read from `fileHandle`. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. + /// - Returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. public func read( fileHandle: NIOFileHandle, byteCount: Int, @@ -318,16 +319,16 @@ public struct NonBlockingFileIO: Sendable { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `fileHandle` in multiple threads. /// - /// - note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. - /// - note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of raw `NIOFileHandle`s. + /// - Note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. + /// - Note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of raw `NIOFileHandle`s. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read. /// - fileOffset: The offset to read from. /// - byteCount: The number of bytes to read from `fileHandle`. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. + /// - Returns: An `EventLoopFuture` which delivers a `ByteBuffer` if the read was successful or a failure on error. public func read( fileHandle: NIOFileHandle, fromOffset fileOffset: Int64, @@ -415,11 +416,11 @@ public struct NonBlockingFileIO: Sendable { /// If `size` is smaller than the current file size, the remaining bytes will be truncated and are lost. If `size` /// is larger than the current file size, the gap will be filled with zero bytes. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - size: The new file size in bytes to write. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. + /// - Returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. public func changeFileSize( fileHandle: NIOFileHandle, size: Int64, @@ -434,10 +435,10 @@ public struct NonBlockingFileIO: Sendable { /// Returns the length of the file in bytes associated with `fileHandle`. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read from. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which is fulfilled with the length of the file in bytes if the write was successful or fails on error. + /// - Returns: An `EventLoopFuture` which is fulfilled with the length of the file in bytes if the write was successful or fails on error. public func readFileSize( fileHandle: NIOFileHandle, eventLoop: EventLoop @@ -454,11 +455,11 @@ public struct NonBlockingFileIO: Sendable { /// Write `buffer` to `fileHandle` in ``NonBlockingFileIO``'s private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - buffer: The `ByteBuffer` to write. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. + /// - Returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. public func write( fileHandle: NIOFileHandle, buffer: ByteBuffer, @@ -469,12 +470,12 @@ public struct NonBlockingFileIO: Sendable { /// Write `buffer` starting from `toOffset` to `fileHandle` in ``NonBlockingFileIO``'s private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - toOffset: The file offset to write to. /// - buffer: The `ByteBuffer` to write. /// - eventLoop: The `EventLoop` to create the returned `EventLoopFuture` from. - /// - returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. + /// - Returns: An `EventLoopFuture` which is fulfilled if the write was successful or fails on error. public func write( fileHandle: NIOFileHandle, toOffset: Int64, @@ -546,12 +547,12 @@ public struct NonBlockingFileIO: Sendable { /// This function will return (a future) of the `NIOFileHandle` associated with the file opened and a `FileRegion` /// comprising of the whole file. The caller must close the returned `NIOFileHandle` when it's no longer needed. /// - /// - note: The reason this returns the `NIOFileHandle` and the `FileRegion` is that both the opening of a file as well as the querying of its size are blocking. + /// - Note: The reason this returns the `NIOFileHandle` and the `FileRegion` is that both the opening of a file as well as the querying of its size are blocking. /// - /// - parameters: - /// - path: The path of the file to be opened for reading. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` containing the `NIOFileHandle` and the `FileRegion` comprising the whole file. + /// - Parameters: + /// - path: The path of the file to be opened for reading. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` containing the `NIOFileHandle` and the `FileRegion` comprising the whole file. public func openFile(path: String, eventLoop: EventLoop) -> EventLoopFuture<(NIOFileHandle, FileRegion)> { self.threadPool.runIfActive(eventLoop: eventLoop) { let fh = try NIOFileHandle(path: path) @@ -570,12 +571,12 @@ public struct NonBlockingFileIO: Sendable { /// This function will return (a future) of the `NIOFileHandle` associated with the file opened. /// The caller must close the returned `NIOFileHandle` when it's no longer needed. /// - /// - parameters: - /// - path: The path of the file to be opened for writing. - /// - mode: File access mode. - /// - flags: Additional POSIX flags. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` containing the `NIOFileHandle`. + /// - Parameters: + /// - path: The path of the file to be opened for writing. + /// - mode: File access mode. + /// - flags: Additional POSIX flags. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` containing the `NIOFileHandle`. public func openFile( path: String, mode: NIOFileHandle.Mode, @@ -590,12 +591,12 @@ public struct NonBlockingFileIO: Sendable { #if !os(Windows) /// Returns information about a file at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - note: If `path` is a symlink, information about the link, not the file it points to. + /// - Note: If `path` is a symlink, information about the link, not the file it points to. /// - /// - parameters: - /// - path: The path of the file to get information about. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` containing file information. + /// - Parameters: + /// - path: The path of the file to get information about. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` containing file information. public func lstat(path: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { var s = stat() @@ -606,11 +607,11 @@ public struct NonBlockingFileIO: Sendable { /// Creates a symbolic link to a `destination` file at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the link. - /// - destination: Target path where this link will point to. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. + /// - Parameters: + /// - path: The path of the link. + /// - destination: Target path where this link will point to. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. public func symlink(path: String, to destination: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { try Posix.symlink(pathname: path, destination: destination) @@ -619,10 +620,10 @@ public struct NonBlockingFileIO: Sendable { /// Returns target of the symbolic link at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the link to read. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` containing link target. + /// - Parameters: + /// - path: The path of the link to read. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` containing link target. public func readlink(path: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { let maxLength = Int(PATH_MAX) @@ -637,10 +638,10 @@ public struct NonBlockingFileIO: Sendable { /// Removes symbolic link at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the link to remove. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. + /// - Parameters: + /// - path: The path of the link to remove. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. public func unlink(path: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { try Posix.unlink(pathname: path) @@ -704,11 +705,12 @@ public struct NonBlockingFileIO: Sendable { /// Creates directory at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the directory to be created. - /// - withIntermediateDirectories: Whether intermediate directories should be created. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. + /// - Parameters: + /// - path: The path of the directory to be created. + /// - createIntermediates: Whether intermediate directories should be created. + /// - mode: POSIX file mode. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. public func createDirectory( path: String, withIntermediateDirectories createIntermediates: Bool = false, @@ -730,10 +732,10 @@ public struct NonBlockingFileIO: Sendable { /// List contents of the directory at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the directory to list the content of. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` containing the directory entries. + /// - Parameters: + /// - path: The path of the directory to list the content of. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` containing the directory entries. public func listDirectory(path: String, eventLoop: EventLoop) -> EventLoopFuture<[NIODirectoryEntry]> { self.threadPool.runIfActive(eventLoop: eventLoop) { let dir = try Posix.opendir(pathname: path) @@ -759,11 +761,11 @@ public struct NonBlockingFileIO: Sendable { /// Renames the file at `path` to `newName` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the file to be renamed. - /// - newName: New file name. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. + /// - Parameters: + /// - path: The path of the file to be renamed. + /// - newName: New file name. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` which is fulfilled if the rename was successful or fails on error. public func rename(path: String, newName: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { try Posix.rename(pathname: path, newName: newName) @@ -772,10 +774,10 @@ public struct NonBlockingFileIO: Sendable { /// Removes the file at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the file to be removed. - /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. - /// - returns: An `EventLoopFuture` which is fulfilled if the remove was successful or fails on error. + /// - Parameters: + /// - path: The path of the file to be removed. + /// - eventLoop: The `EventLoop` on which the returned `EventLoopFuture` will fire. + /// - Returns: An `EventLoopFuture` which is fulfilled if the remove was successful or fails on error. public func remove(path: String, eventLoop: EventLoop) -> EventLoopFuture { self.threadPool.runIfActive(eventLoop: eventLoop) { try Posix.remove(pathname: path) @@ -811,13 +813,13 @@ extension NonBlockingFileIO { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `FileRegion` in multiple threads. /// - /// - note: Only use this function for small enough `FileRegion`s as it will need to allocate enough memory to hold `fileRegion.readableBytes` bytes. - /// - note: In most cases you should prefer one of the `readChunked` functions. + /// - Note: Only use this function for small enough `FileRegion`s as it will need to allocate enough memory to hold `fileRegion.readableBytes` bytes. + /// - Note: In most cases you should prefer one of the `readChunked` functions. /// - /// - parameters: + /// - Parameters: /// - fileRegion: The file region to read. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. - /// - returns: ByteBuffer. + /// - Returns: ByteBuffer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func read(fileRegion: FileRegion, allocator: ByteBufferAllocator) async throws -> ByteBuffer { let readableBytes = fileRegion.readableBytes @@ -834,18 +836,18 @@ extension NonBlockingFileIO { /// The returned `ByteBuffer` will not have less than `byteCount` bytes unless we hit end-of-file in which /// case the `ByteBuffer` will contain the bytes available to read. /// - /// - note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. - /// - note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of + /// - Note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. + /// - Note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of /// raw `NIOFileHandle`s. In case you do want to use raw `NIOFileHandle`s, /// please consider using ``read(fileHandle:fromOffset:byteCount:allocator:eventLoop:)`` /// because it doesn't use the file descriptor's seek pointer (which may be shared with other file /// descriptors and even across processes.) /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read. /// - byteCount: The number of bytes to read from `fileHandle`. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. - /// - returns: ByteBuffer. + /// - Returns: ByteBuffer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func read( fileHandle: NIOFileHandle, @@ -869,15 +871,15 @@ extension NonBlockingFileIO { /// This method will not use the file descriptor's seek pointer which means there is no danger of reading from the /// same `fileHandle` in multiple threads. /// - /// - note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. - /// - note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of raw `NIOFileHandle`s. + /// - Note: Only use this function for small enough `byteCount`s as it will need to allocate enough memory to hold `byteCount` bytes. + /// - Note: ``read(fileRegion:allocator:eventLoop:)`` should be preferred as it uses `FileRegion` object instead of raw `NIOFileHandle`s. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read. /// - fileOffset: The offset to read from. /// - byteCount: The number of bytes to read from `fileHandle`. /// - allocator: A `ByteBufferAllocator` used to allocate space for the returned `ByteBuffer`. - /// - returns: ByteBuffer. + /// - Returns: ByteBuffer. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func read( fileHandle: NIOFileHandle, @@ -920,7 +922,7 @@ extension NonBlockingFileIO { /// If `size` is smaller than the current file size, the remaining bytes will be truncated and are lost. If `size` /// is larger than the current file size, the gap will be filled with zero bytes. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - size: The new file size in bytes to write. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -937,7 +939,7 @@ extension NonBlockingFileIO { /// Returns the length of the file associated with `fileHandle`. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to read from. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func readFileSize(fileHandle: NIOFileHandle) async throws -> Int64 { @@ -953,7 +955,7 @@ extension NonBlockingFileIO { /// Write `buffer` to `fileHandle` in ``NonBlockingFileIO``'s private thread pool. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - buffer: The `ByteBuffer` to write. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) @@ -966,7 +968,7 @@ extension NonBlockingFileIO { /// Write `buffer` starting from `toOffset` to `fileHandle` in ``NonBlockingFileIO``'s private thread pool. /// - /// - parameters: + /// - Parameters: /// - fileHandle: The `NIOFileHandle` to write to. /// - toOffset: The file offset to write to. /// - buffer: The `ByteBuffer` to write. @@ -1001,12 +1003,12 @@ extension NonBlockingFileIO { /// /// The will return the result of the operation. /// - /// - note: This function opens a file and queries it size which are both blocking operations + /// - Note: This function opens a file and queries it size which are both blocking operations /// - /// - parameters: - /// - path: The path of the file to be opened for reading. - /// - body: operation to run with file handle and region - /// - returns: return value of operation + /// - Parameters: + /// - path: The path of the file to be opened for reading. + /// - body: operation to run with file handle and region + /// - Returns: return value of operation @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func withFileRegion( path: String, @@ -1037,11 +1039,12 @@ extension NonBlockingFileIO { /// /// This function will return the result of the operation. /// - /// - parameters: - /// - path: The path of the file to be opened for writing. - /// - mode: File access mode. - /// - flags: Additional POSIX flags. - /// - returns: return value of operation + /// - Parameters: + /// - path: The path of the file to be opened for writing. + /// - mode: File access mode. + /// - flags: Additional POSIX flags. + /// - body: operation to run with the file handle + /// - Returns: return value of operation @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func withFileHandle( path: String, @@ -1067,11 +1070,11 @@ extension NonBlockingFileIO { /// Returns information about a file at `path` on a private thread pool. /// - /// - note: If `path` is a symlink, information about the link, not the file it points to. + /// - Note: If `path` is a symlink, information about the link, not the file it points to. /// - /// - parameters: - /// - path: The path of the file to get information about. - /// - returns: file information. + /// - Parameters: + /// - path: The path of the file to get information about. + /// - Returns: file information. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func lstat(path: String) async throws -> stat { try await self.threadPool.runIfActive { @@ -1083,9 +1086,9 @@ extension NonBlockingFileIO { /// Creates a symbolic link to a `destination` file at `path` on a private thread pool. /// - /// - parameters: - /// - path: The path of the link. - /// - destination: Target path where this link will point to. + /// - Parameters: + /// - path: The path of the link. + /// - destination: Target path where this link will point to. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func symlink(path: String, to destination: String) async throws { try await self.threadPool.runIfActive { @@ -1095,9 +1098,9 @@ extension NonBlockingFileIO { /// Returns target of the symbolic link at `path` on a private thread pool. /// - /// - parameters: - /// - path: The path of the link to read. - /// - returns: link target. + /// - Parameters: + /// - path: The path of the link to read. + /// - Returns: link target. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func readlink(path: String) async throws -> String { try await self.threadPool.runIfActive { @@ -1113,8 +1116,8 @@ extension NonBlockingFileIO { /// Removes symbolic link at `path` on a private thread pool which is separate from any `EventLoop` thread. /// - /// - parameters: - /// - path: The path of the link to remove. + /// - Parameters: + /// - path: The path of the link to remove. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func unlink(path: String) async throws { try await self.threadPool.runIfActive { @@ -1124,9 +1127,10 @@ extension NonBlockingFileIO { /// Creates directory at `path` on a private thread pool. /// - /// - parameters: - /// - path: The path of the directory to be created. - /// - withIntermediateDirectories: Whether intermediate directories should be created. + /// - Parameters: + /// - path: The path of the directory to be created. + /// - createIntermediates: Whether intermediate directories should be created. + /// - mode: POSIX file mode. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func createDirectory( path: String, @@ -1148,9 +1152,9 @@ extension NonBlockingFileIO { /// List contents of the directory at `path` on a private thread pool. /// - /// - parameters: - /// - path: The path of the directory to list the content of. - /// - returns: The directory entries. + /// - Parameters: + /// - path: The path of the directory to list the content of. + /// - Returns: The directory entries. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func listDirectory(path: String) async throws -> [NIODirectoryEntry] { try await self.threadPool.runIfActive { @@ -1177,9 +1181,9 @@ extension NonBlockingFileIO { /// Renames the file at `path` to `newName` on a private thread pool. /// - /// - parameters: - /// - path: The path of the file to be renamed. - /// - newName: New file name. + /// - Parameters: + /// - path: The path of the file to be renamed. + /// - newName: New file name. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func rename(path: String, newName: String) async throws { try await self.threadPool.runIfActive { @@ -1189,8 +1193,8 @@ extension NonBlockingFileIO { /// Removes the file at `path` on a private thread pool. /// - /// - parameters: - /// - path: The path of the file to be removed. + /// - Parameters: + /// - path: The path of the file to be removed. @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) public func remove(path: String) async throws { try await self.threadPool.runIfActive { diff --git a/Sources/NIOPosix/PendingDatagramWritesManager.swift b/Sources/NIOPosix/PendingDatagramWritesManager.swift index 8945df0692..ace953fbcc 100644 --- a/Sources/NIOPosix/PendingDatagramWritesManager.swift +++ b/Sources/NIOPosix/PendingDatagramWritesManager.swift @@ -50,7 +50,7 @@ private struct PendingDatagramWrite { extension Error { /// Returns whether the error is "recoverable" from the perspective of datagram sending. /// - /// - returns: `true` if the error is recoverable, `false` otherwise. + /// - Returns: `true` if the error is recoverable, `false` otherwise. fileprivate var isRecoverable: Bool { switch self { case let e as IOError where e.errnoCode == EMSGSIZE, @@ -193,7 +193,7 @@ private struct PendingDatagramWritesState { /// Indicates that the first outstanding write was written. /// - /// - returns: The promise that the caller must fire, along with an error to fire it with if it needs one. + /// - Returns: The promise that the caller must fire, along with an error to fire it with if it needs one. private mutating func wroteFirst(error: Error? = nil) -> DatagramWritePromiseFiller? { let first = self.pendingWrites.removeFirst() self.chunks -= 1 @@ -242,10 +242,10 @@ private struct PendingDatagramWritesState { /// /// - warning: The closure will simply fulfill all the promises in order. If one of those promises does for example close the `Channel` we might see subsequent writes fail out of order. Example: Imagine the user issues three writes: `A`, `B` and `C`. Imagine that `A` and `B` both get successfully written in one write operation but the user closes the `Channel` in `A`'s callback. Then overall the promises will be fulfilled in this order: 1) `A`: success 2) `C`: error 3) `B`: success. Note how `B` and `C` get fulfilled out of order. /// - /// - parameters: - /// - data: The result of the write operation: namely, for each datagram we attempted to write, the number of bytes we wrote. - /// - messages: The vector messages written, if any. - /// - returns: A promise and the error that should be sent to it, if any, and a `WriteResult` which indicates if we could write everything or not. + /// - Parameters: + /// - data: The result of the write operation: namely, for each datagram we attempted to write, the number of bytes we wrote. + /// - messages: The vector messages written, if any. + /// - Returns: A promise and the error that should be sent to it, if any, and a `WriteResult` which indicates if we could write everything or not. public mutating func didWrite( _ data: IOResult, messages: UnsafeMutableBufferPointer? @@ -273,10 +273,10 @@ private struct PendingDatagramWritesState { /// Indicates that a vector write succeeded. /// - /// - parameters: - /// - written: The number of messages successfully written. - /// - messages: The list of message objects. - /// - returns: A closure that the caller _needs_ to run which will fulfill the promises of the writes, and a `WriteResult` that indicates if we could write + /// - Parameters: + /// - written: The number of messages successfully written. + /// - messages: The list of message objects. + /// - Returns: A closure that the caller _needs_ to run which will fulfill the promises of the writes, and a `WriteResult` that indicates if we could write /// everything or not. private mutating func didVectorWrite( written: Int, @@ -309,9 +309,9 @@ private struct PendingDatagramWritesState { /// Indicates that a scalar write succeeded. /// - /// - parameters: - /// - written: The number of bytes successfully written. - /// - returns: All the promises that must be fired, and a `WriteResult` that indicates if we could write + /// - Parameters: + /// - written: The number of bytes successfully written. + /// - Returns: All the promises that must be fired, and a `WriteResult` that indicates if we could write /// everything or not. private mutating func didScalarWrite(written: Int) -> (DatagramWritePromiseFiller?, OneWriteOperationResult) { precondition( @@ -333,7 +333,7 @@ private struct PendingDatagramWritesState { /// /// - warning: See the warning for `didWrite`. /// - /// - returns: Nothing + /// - Returns: Nothing public mutating func failAll(error: Error) { var promises: [EventLoopPromise] = [] promises.reserveCapacity(self.pendingWrites.count) @@ -423,9 +423,9 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// `EventLoop` always runs on one and the same thread. That means that there can't be any writes of more than /// one `Channel` on the same `EventLoop` at the same time. /// - /// - parameters: - /// - bufferPool: a pool of buffers to be used for IOVector and storage references - /// - msgBufferPool: a pool of buffers to be usded for `MMsgHdr`, `sockaddr_storage` and cmsghdr elements + /// - Parameters: + /// - bufferPool: a pool of buffers to be used for IOVector and storage references + /// - msgBufferPool: a pool of buffers to be usded for `MMsgHdr`, `sockaddr_storage` and cmsghdr elements init(bufferPool: Pool, msgBufferPool: Pool) { self.bufferPool = bufferPool self.msgBufferPool = msgBufferPool @@ -471,10 +471,10 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// Add a pending write, with an `AddressedEnvelope`, usually on an unconnected socket. /// - /// - parameters: - /// - envelope: The `AddressedEnvelope` to write. - /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result - /// - returns: If the `Channel` is still writable after adding the write of `data`. + /// - Parameters: + /// - envelope: The `AddressedEnvelope` to write. + /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result + /// - Returns: If the `Channel` is still writable after adding the write of `data`. /// /// - warning: If the socket is connected, then the `envelope.remoteAddress` _must_ match the /// address of the connected peer, otherwise this function will throw a fatal error. @@ -508,10 +508,10 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// Add a pending write, without an `AddressedEnvelope`, on a connected socket. /// - /// - parameters: - /// - data: The `ByteBuffer` to write. - /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result - /// - returns: If the `Channel` is still writable after adding the write of `data`. + /// - Parameters: + /// - data: The `ByteBuffer` to write. + /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result + /// - Returns: If the `Channel` is still writable after adding the write of `data`. func add(data: ByteBuffer, promise: EventLoopPromise?) -> Bool { self.add( PendingDatagramWrite( @@ -531,10 +531,10 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// Triggers the appropriate write operation. This is a fancy way of saying trigger either `sendto` or `sendmmsg`. /// On platforms that do not support a gathering write operation, /// - /// - parameters: - /// - scalarWriteOperation: An operation that writes a single, contiguous array of bytes (usually `sendmsg`). - /// - vectorWriteOperation: An operation that writes multiple contiguous arrays of bytes (usually `sendmmsg`). - /// - returns: The `WriteResult` and whether the `Channel` is now writable. + /// - Parameters: + /// - scalarWriteOperation: An operation that writes a single, contiguous array of bytes (usually `sendmsg`). + /// - vectorWriteOperation: An operation that writes multiple contiguous arrays of bytes (usually `sendmmsg`). + /// - Returns: The `WriteResult` and whether the `Channel` is now writable. func triggerAppropriateWriteOperations( scalarWriteOperation: ( UnsafeRawBufferPointer, UnsafePointer?, socklen_t, AddressedEnvelope.Metadata? @@ -571,8 +571,8 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// To be called after a write operation (usually selected and run by `triggerAppropriateWriteOperation`) has /// completed. /// - /// - parameters: - /// - data: The result of the write operation. + /// - Parameters: + /// - data: The result of the write operation. private func didWrite( _ data: IOResult, messages: UnsafeMutableBufferPointer? @@ -591,10 +591,10 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// useful errors and fail the individual write, rather than fail the entire connection. If the error cannot /// be tolerated by a datagram application, will rethrow the error. /// - /// - parameters: - /// - error: The error we hit. - /// - returns: A `WriteResult` indicating whether the writes should continue. - /// - throws: Any error that cannot be ignored by a datagram write. + /// - Parameters: + /// - error: The error we hit. + /// - Returns: A `WriteResult` indicating whether the writes should continue. + /// - Throws: Any error that cannot be ignored by a datagram write. private func handleError(_ error: Error) throws -> OneWriteOperationResult { switch error { case let e as IOError where e.errnoCode == EMSGSIZE: @@ -612,8 +612,8 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// Trigger a write of a single object where an object can either be a contiguous array of bytes or a region of a file. /// - /// - parameters: - /// - scalarWriteOperation: An operation that writes a single, contiguous array of bytes (usually `sendto`). + /// - Parameters: + /// - scalarWriteOperation: An operation that writes a single, contiguous array of bytes (usually `sendto`). private func triggerScalarBufferWrite( scalarWriteOperation: ( UnsafeRawBufferPointer, UnsafePointer?, socklen_t, AddressedEnvelope.Metadata? @@ -655,8 +655,8 @@ final class PendingDatagramWritesManager: PendingWritesManager { /// Trigger a vector write operation. In other words: Write multiple contiguous arrays of bytes. /// - /// - parameters: - /// - vectorWriteOperation: The vector write operation to use. Usually `sendmmsg`. + /// - Parameters: + /// - vectorWriteOperation: The vector write operation to use. Usually `sendmmsg`. private func triggerVectorBufferWrite( vectorWriteOperation: (UnsafeMutableBufferPointer) throws -> IOResult ) throws -> OneWriteOperationResult { diff --git a/Sources/NIOPosix/PendingWritesManager.swift b/Sources/NIOPosix/PendingWritesManager.swift index 02f82cbb1c..83323f480f 100644 --- a/Sources/NIOPosix/PendingWritesManager.swift +++ b/Sources/NIOPosix/PendingWritesManager.swift @@ -22,11 +22,11 @@ private struct PendingStreamWrite { /// Does the setup required to issue a writev. /// -/// - parameters: +/// - Parameters: /// - pending: The currently pending writes. /// - bufferPool: Pool of buffers to use for iovecs and storageRefs /// - body: The function that actually does the vector write (usually `writev`). -/// - returns: A tuple of the number of items attempted to write and the result of the write operation. +/// - Returns: A tuple of the number of items attempted to write and the result of the write operation. private func doPendingWriteVectorOperation( pending: PendingStreamWritesState, bufferPool: Pool, @@ -134,7 +134,7 @@ private struct PendingStreamWritesState { /// Indicates that the first outstanding write was written in its entirety. /// - /// - returns: The `EventLoopPromise` of the write or `nil` if none was provided. The promise needs to be fulfilled by the caller. + /// - Returns: The `EventLoopPromise` of the write or `nil` if none was provided. The promise needs to be fulfilled by the caller. /// private mutating func fullyWrittenFirst() -> EventLoopPromise? { let first = self.pendingWrites.removeFirst() @@ -144,8 +144,8 @@ private struct PendingStreamWritesState { /// Indicates that the first outstanding object has been partially written. /// - /// - parameters: - /// - bytes: How many bytes of the item were written. + /// - Parameters: + /// - bytes: How many bytes of the item were written. private mutating func partiallyWrittenFirst(bytes: Int) { self.pendingWrites[self.pendingWrites.startIndex].data.moveReaderIndex(forwardBy: bytes) self.subtractOutstanding(bytes: bytes) @@ -193,9 +193,9 @@ private struct PendingStreamWritesState { /// /// - warning: The promises will be returned in order. If one of those promises does for example close the `Channel` we might see subsequent writes fail out of order. Example: Imagine the user issues three writes: `A`, `B` and `C`. Imagine that `A` and `B` both get successfully written in one write operation but the user closes the `Channel` in `A`'s callback. Then overall the promises will be fulfilled in this order: 1) `A`: success 2) `C`: error 3) `B`: success. Note how `B` and `C` get fulfilled out of order. /// - /// - parameters: - /// - writeResult: The result of the write operation. - /// - returns: A tuple of a promise and a `OneWriteResult`. The promise is the first promise that needs to be notified of the write result. + /// - Parameters: + /// - writeResult: The result of the write operation. + /// - Returns: A tuple of a promise and a `OneWriteResult`. The promise is the first promise that needs to be notified of the write result. /// This promise will cascade the result to all other promises that need notifying. If no promises need to be notified, will be `nil`. /// The write result will indicate whether we were able to write everything or not. public mutating func didWrite( @@ -246,7 +246,7 @@ private struct PendingStreamWritesState { /// /// - warning: See the warning for `didWrite`. /// - /// - returns: promise that needs to be failed, or `nil` if there were no pending writes. + /// - Returns: promise that needs to be failed, or `nil` if there were no pending writes. public mutating func removeAll() -> EventLoopPromise? { var promise0: EventLoopPromise? @@ -330,9 +330,9 @@ final class PendingStreamWritesManager: PendingWritesManager { /// Add a pending write alongside its promise. /// - /// - parameters: - /// - data: The `IOData` to write. - /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result + /// - Parameters: + /// - data: The `IOData` to write. + /// - promise: Optionally an `EventLoopPromise` that will get the write operation's result /// - result: If the `Channel` is still writable after adding the write of `data`. func add(data: IOData, promise: EventLoopPromise?) -> Bool { assert(self.isOpen) @@ -356,11 +356,11 @@ final class PendingStreamWritesManager: PendingWritesManager { /// Triggers the appropriate write operation. This is a fancy way of saying trigger either `write`, `writev` or /// `sendfile`. /// - /// - parameters: - /// - scalarBufferWriteOperation: An operation that writes a single, contiguous array of bytes (usually `write`). - /// - vectorBufferWriteOperation: An operation that writes multiple contiguous arrays of bytes (usually `writev`). - /// - scalarFileWriteOperation: An operation that writes a region of a file descriptor (usually `sendfile`). - /// - returns: The `OneWriteOperationResult` and whether the `Channel` is now writable. + /// - Parameters: + /// - scalarBufferWriteOperation: An operation that writes a single, contiguous array of bytes (usually `write`). + /// - vectorBufferWriteOperation: An operation that writes multiple contiguous arrays of bytes (usually `writev`). + /// - scalarFileWriteOperation: An operation that writes a region of a file descriptor (usually `sendfile`). + /// - Returns: The `OneWriteOperationResult` and whether the `Channel` is now writable. func triggerAppropriateWriteOperations( scalarBufferWriteOperation: (UnsafeRawBufferPointer) throws -> IOResult, vectorBufferWriteOperation: (UnsafeBufferPointer) throws -> IOResult, @@ -384,9 +384,9 @@ final class PendingStreamWritesManager: PendingWritesManager { /// To be called after a write operation (usually selected and run by `triggerAppropriateWriteOperation`) has /// completed. /// - /// - parameters: - /// - itemCount: The number of items we tried to write. - /// - result: The result of the write operation. + /// - Parameters: + /// - itemCount: The number of items we tried to write. + /// - result: The result of the write operation. private func didWrite(itemCount: Int, result: IOResult) -> OneWriteOperationResult { let (promise, result) = self.state.didWrite(itemCount: itemCount, result: result) @@ -400,8 +400,8 @@ final class PendingStreamWritesManager: PendingWritesManager { /// Trigger a write of a single `ByteBuffer` (usually using `write(2)`). /// - /// - parameters: - /// - operation: An operation that writes a single, contiguous array of bytes (usually `write`). + /// - Parameters: + /// - operation: An operation that writes a single, contiguous array of bytes (usually `write`). private func triggerScalarBufferWrite( _ operation: (UnsafeRawBufferPointer) throws -> IOResult ) throws -> OneWriteOperationResult { @@ -420,8 +420,8 @@ final class PendingStreamWritesManager: PendingWritesManager { /// Trigger a write of a single `FileRegion` (usually using `sendfile(2)`). /// - /// - parameters: - /// - operation: An operation that writes a region of a file descriptor. + /// - Parameters: + /// - operation: An operation that writes a region of a file descriptor. private func triggerScalarFileWrite( _ operation: (CInt, Int, Int) throws -> IOResult ) throws -> OneWriteOperationResult { @@ -444,8 +444,8 @@ final class PendingStreamWritesManager: PendingWritesManager { /// Trigger a vector write operation. In other words: Write multiple contiguous arrays of bytes. /// - /// - parameters: - /// - operation: The vector write operation to use. Usually `writev`. + /// - Parameters: + /// - operation: The vector write operation to use. Usually `writev`. private func triggerVectorBufferWrite( _ operation: (UnsafeBufferPointer) throws -> IOResult ) throws -> OneWriteOperationResult { @@ -478,8 +478,8 @@ final class PendingStreamWritesManager: PendingWritesManager { /// `EventLoop` always runs on one and the same thread. That means that there can't be any writes of more than /// one `Channel` on the same `EventLoop` at the same time. /// - /// - parameters: - /// - bufferPool: Pool of buffers to be used for iovecs and storage references + /// - Parameters: + /// - bufferPool: Pool of buffers to be used for iovecs and storage references init(bufferPool: Pool) { self.bufferPool = bufferPool } diff --git a/Sources/NIOPosix/Pool.swift b/Sources/NIOPosix/Pool.swift index f4856a9dab..c2274e9d84 100644 --- a/Sources/NIOPosix/Pool.swift +++ b/Sources/NIOPosix/Pool.swift @@ -89,9 +89,9 @@ struct PooledBuffer: PoolElement { /// the bytes and you also must call `storageManagement.release()` if you no longer require those bytes. Calls to /// `retain` and `release` must be balanced. /// - /// - parameters: - /// - body: The closure that will accept the yielded pointers and the `storageManagement`. - /// - returns: The value returned by `body`. + /// - Parameters: + /// - body: The closure that will accept the yielded pointers and the `storageManagement`. + /// - Returns: The value returned by `body`. func withUnsafePointersWithStorageManagement( _ body: ( UnsafeMutableBufferPointer, UnsafeMutableBufferPointer>, Unmanaged diff --git a/Sources/NIOPosix/PosixSingletons+ConcurrencyTakeOver.swift b/Sources/NIOPosix/PosixSingletons+ConcurrencyTakeOver.swift index 07ee8955ce..64b53d8379 100644 --- a/Sources/NIOPosix/PosixSingletons+ConcurrencyTakeOver.swift +++ b/Sources/NIOPosix/PosixSingletons+ConcurrencyTakeOver.swift @@ -33,7 +33,7 @@ extension NIOSingletons { /// operation doesn't guarantee anything because another piece of code could have done the same without using atomic operations. But we /// do our best. /// - /// - returns: If ``MultiThreadedEventLoopGroup/singleton`` was successfully installed as Swift Concurrency's global executor or not. + /// - Returns: If ``MultiThreadedEventLoopGroup/singleton`` was successfully installed as Swift Concurrency's global executor or not. /// /// - warning: You may only call this method from the main thread. /// - warning: You may only call this method once. diff --git a/Sources/NIOPosix/PosixSingletons.swift b/Sources/NIOPosix/PosixSingletons.swift index 5f47e25167..61bad532e4 100644 --- a/Sources/NIOPosix/PosixSingletons.swift +++ b/Sources/NIOPosix/PosixSingletons.swift @@ -45,7 +45,7 @@ extension MultiThreadedEventLoopGroup { /// /// The loop count of this group is determined by `NIOSingletons/groupLoopCountSuggestion`. /// - /// - note: Users who do not want any code to spawn global singleton resources may set + /// - Note: Users who do not want any code to spawn global singleton resources may set /// `NIOSingletons/singletonsEnabledSuggestion` to `false` which will lead to a forced crash /// if any code attempts to use the global singletons. /// @@ -78,7 +78,7 @@ extension NIOThreadPool { /// /// The thread count of this pool is determined by `NIOSingletons/suggestedBlockingPoolThreadCount`. /// - /// - note: Users who do not want any code to spawn global singleton resources may set + /// - Note: Users who do not want any code to spawn global singleton resources may set /// `NIOSingletons/singletonsEnabledSuggestion` to `false` which will lead to a forced crash /// if any code attempts to use the global singletons. public static var singleton: NIOThreadPool { diff --git a/Sources/NIOPosix/RawSocketBootstrap.swift b/Sources/NIOPosix/RawSocketBootstrap.swift index 5f507fb5e9..72aec18cce 100644 --- a/Sources/NIOPosix/RawSocketBootstrap.swift +++ b/Sources/NIOPosix/RawSocketBootstrap.swift @@ -47,8 +47,8 @@ public final class NIORawSocketBootstrap { /// `MultiThreadedEventLoopGroup.next`. See `init(validatingGroup:)` for a fallible initializer for /// situations where it's impossible to tell ahead of time if the `EventLoopGroup` is compatible or not. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public convenience init(group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { preconditionFailure( @@ -61,8 +61,8 @@ public final class NIORawSocketBootstrap { /// Create a `RawSocketBootstrap` on the `EventLoopGroup` `group`, validating that `group` is compatible. /// - /// - parameters: - /// - group: The `EventLoopGroup` to use. + /// - Parameters: + /// - group: The `EventLoopGroup` to use. public init?(validatingGroup group: EventLoopGroup) { guard NIOOnSocketsBootstraps.isCompatible(group: group) else { return nil @@ -75,8 +75,8 @@ public final class NIORawSocketBootstrap { /// Initialize the bound `Channel` with `initializer`. The most common task in initializer is to add /// `ChannelHandler`s to the `ChannelPipeline`. /// - /// - parameters: - /// - handler: A closure that initializes the provided `Channel`. + /// - Parameters: + /// - handler: A closure that initializes the provided `Channel`. public func channelInitializer(_ handler: @escaping @Sendable (Channel) -> EventLoopFuture) -> Self { self.channelInitializer = handler return self @@ -84,9 +84,9 @@ public final class NIORawSocketBootstrap { /// Specifies a `ChannelOption` to be applied to the `Channel`. /// - /// - parameters: - /// - option: The option to be applied. - /// - value: The value for the option. + /// - Parameters: + /// - option: The option to be applied. + /// - value: The value for the option. @inlinable public func channelOption(_ option: Option, value: Option.Value) -> Self { self._channelOptions.append(key: option, value: value) @@ -96,9 +96,9 @@ public final class NIORawSocketBootstrap { /// Bind the `Channel` to `host`. /// All packets or errors matching the `ipProtocol` specified are passed to the resulting `Channel`. /// - /// - parameters: - /// - host: The host to bind on. - /// - ipProtocol: The IP protocol used in the IP protocol/nextHeader field. + /// - Parameters: + /// - host: The host to bind on. + /// - ipProtocol: The IP protocol used in the IP protocol/nextHeader field. public func bind(host: String, ipProtocol: NIOIPProtocol) -> EventLoopFuture { bind0(ipProtocol: ipProtocol) { try SocketAddress.makeAddressResolvingHost(host, port: 0) @@ -133,9 +133,9 @@ public final class NIORawSocketBootstrap { /// Connect the `Channel` to `host`. /// - /// - parameters: - /// - host: The host to connect to. - /// - ipProtocol: The IP protocol used in the IP protocol/nextHeader field. + /// - Parameters: + /// - host: The host to connect to. + /// - ipProtocol: The IP protocol used in the IP protocol/nextHeader field. public func connect(host: String, ipProtocol: NIOIPProtocol) -> EventLoopFuture { connect0(ipProtocol: ipProtocol) { try SocketAddress.makeAddressResolvingHost(host, port: 0) diff --git a/Sources/NIOPosix/Resolver.swift b/Sources/NIOPosix/Resolver.swift index 9c89c82cd1..414236c35b 100644 --- a/Sources/NIOPosix/Resolver.swift +++ b/Sources/NIOPosix/Resolver.swift @@ -25,18 +25,18 @@ import NIOCore public protocol Resolver { /// Initiate a DNS A query for a given host. /// - /// - parameters: - /// - host: The hostname to do an A lookup on. - /// - port: The port we'll be connecting to. - /// - returns: An `EventLoopFuture` that fires with the result of the lookup. + /// - Parameters: + /// - host: The hostname to do an A lookup on. + /// - port: The port we'll be connecting to. + /// - Returns: An `EventLoopFuture` that fires with the result of the lookup. func initiateAQuery(host: String, port: Int) -> EventLoopFuture<[SocketAddress]> /// Initiate a DNS AAAA query for a given host. /// - /// - parameters: - /// - host: The hostname to do an AAAA lookup on. - /// - port: The port we'll be connecting to. - /// - returns: An `EventLoopFuture` that fires with the result of the lookup. + /// - Parameters: + /// - host: The hostname to do an AAAA lookup on. + /// - port: The port we'll be connecting to. + /// - Returns: An `EventLoopFuture` that fires with the result of the lookup. func initiateAAAAQuery(host: String, port: Int) -> EventLoopFuture<[SocketAddress]> /// Cancel all outstanding DNS queries. diff --git a/Sources/NIOPosix/SelectorEpoll.swift b/Sources/NIOPosix/SelectorEpoll.swift index 5b5ea844cc..61a1132a15 100644 --- a/Sources/NIOPosix/SelectorEpoll.swift +++ b/Sources/NIOPosix/SelectorEpoll.swift @@ -201,9 +201,9 @@ extension Selector: _SelectorBackendProtocol { /// Apply the given `SelectorStrategy` and execute `body` once it's complete (which may produce `SelectorEvent`s to handle). /// - /// - parameters: - /// - strategy: The `SelectorStrategy` to apply - /// - body: The function to execute for each `SelectorEvent` that was produced. + /// - Parameters: + /// - strategy: The `SelectorStrategy` to apply + /// - body: The function to execute for each `SelectorEvent` that was produced. func whenReady0( strategy: SelectorStrategy, onLoopBegin loopStart: () -> Void, diff --git a/Sources/NIOPosix/SelectorGeneric.swift b/Sources/NIOPosix/SelectorGeneric.swift index f865021bd7..db4d5ce5b4 100644 --- a/Sources/NIOPosix/SelectorGeneric.swift +++ b/Sources/NIOPosix/SelectorGeneric.swift @@ -76,7 +76,7 @@ struct SelectorEventSet: OptionSet, Equatable { /// EOF at the write/output end of a `Selectable`. /// - /// - note: This is rarely used because in many cases, there is no signal that this happened. + /// - Note: This is rarely used because in many cases, there is no signal that this happened. static let writeEOF = SelectorEventSet(rawValue: 1 << 4) init(rawValue: SelectorEventSet.RawValue) { @@ -124,9 +124,9 @@ protocol _SelectorBackendProtocol { func wakeup0() throws /// Apply the given `SelectorStrategy` and execute `body` once it's complete (which may produce `SelectorEvent`s to handle). /// - /// - parameters: - /// - strategy: The `SelectorStrategy` to apply - /// - body: The function to execute for each `SelectorEvent` that was produced. + /// - Parameters: + /// - strategy: The `SelectorStrategy` to apply + /// - body: The function to execute for each `SelectorEvent` that was produced. func whenReady0( strategy: SelectorStrategy, onLoopBegin: () -> Void, @@ -227,10 +227,10 @@ internal class Selector { /// Register `Selectable` on the `Selector`. /// - /// - parameters: - /// - selectable: The `Selectable` to register. - /// - interested: The `SelectorEventSet` in which we are interested and want to be notified about. - /// - makeRegistration: Creates the registration data for the given `SelectorEventSet`. + /// - Parameters: + /// - selectable: The `Selectable` to register. + /// - interested: The `SelectorEventSet` in which we are interested and want to be notified about. + /// - makeRegistration: Creates the registration data for the given `SelectorEventSet`. func register( selectable: S, interested: SelectorEventSet, @@ -257,9 +257,9 @@ internal class Selector { /// Re-register `Selectable`, must be registered via `register` before. /// - /// - parameters: - /// - selectable: The `Selectable` to re-register. - /// - interested: The `SelectorEventSet` in which we are interested and want to be notified about. + /// - Parameters: + /// - selectable: The `Selectable` to re-register. + /// - interested: The `SelectorEventSet` in which we are interested and want to be notified about. func reregister(selectable: S, interested: SelectorEventSet) throws { assert(self.myThread == NIOThread.current) guard self.lifecycleState == .open else { @@ -284,8 +284,8 @@ internal class Selector { /// /// After the `Selectable is deregistered no `SelectorEventSet` will be produced anymore for the `Selectable`. /// - /// - parameters: - /// - selectable: The `Selectable` to deregister. + /// - Parameters: + /// - selectable: The `Selectable` to deregister. func deregister(selectable: S) throws { assert(self.myThread == NIOThread.current) guard self.lifecycleState == .open else { @@ -307,10 +307,10 @@ internal class Selector { /// Apply the given `SelectorStrategy` and execute `body` once it's complete (which may produce `SelectorEvent`s to handle). /// - /// - parameters: - /// - strategy: The `SelectorStrategy` to apply - /// - onLoopBegin: A function executed after the selector returns, just before the main loop begins.. - /// - body: The function to execute for each `SelectorEvent` that was produced. + /// - Parameters: + /// - strategy: The `SelectorStrategy` to apply + /// - onLoopBegin: A function executed after the selector returns, just before the main loop begins.. + /// - body: The function to execute for each `SelectorEvent` that was produced. func whenReady( strategy: SelectorStrategy, onLoopBegin loopStart: () -> Void, @@ -361,9 +361,9 @@ struct SelectorEvent { /// Create new instance /// - /// - parameters: - /// - io: The `SelectorEventSet` that triggered this event. - /// - registration: The registration that belongs to the event. + /// - Parameters: + /// - io: The `SelectorEventSet` that triggered this event. + /// - registration: The registration that belongs to the event. init(io: SelectorEventSet, registration: R) { self.io = io self.registration = registration diff --git a/Sources/NIOPosix/SelectorKqueue.swift b/Sources/NIOPosix/SelectorKqueue.swift index dc00367808..26d13298c1 100644 --- a/Sources/NIOPosix/SelectorKqueue.swift +++ b/Sources/NIOPosix/SelectorKqueue.swift @@ -58,7 +58,7 @@ extension KQueueEventFilterSet { /// Calculate the kqueue filter changes that are necessary to transition from `previousKQueueFilterSet` to `self`. /// The `body` closure is then called with the changes necessary expressed as a number of `kevent`. /// - /// - parameters: + /// - Parameters: /// - previousKQueueFilterSet: The previous filter set that is currently registered with kqueue. /// - fileDescriptor: The file descriptor the `kevent`s should be generated to. /// - body: The closure that will then apply the change set. @@ -248,9 +248,9 @@ extension Selector: _SelectorBackendProtocol { /// Apply the given `SelectorStrategy` and execute `body` once it's complete (which may produce `SelectorEvent`s to handle). /// - /// - parameters: - /// - strategy: The `SelectorStrategy` to apply - /// - body: The function to execute for each `SelectorEvent` that was produced. + /// - Parameters: + /// - strategy: The `SelectorStrategy` to apply + /// - body: The function to execute for each `SelectorEvent` that was produced. func whenReady0( strategy: SelectorStrategy, onLoopBegin loopStart: () -> Void, diff --git a/Sources/NIOPosix/SelectorUring.swift b/Sources/NIOPosix/SelectorUring.swift index e8c0ba84e9..2bc9fdb379 100644 --- a/Sources/NIOPosix/SelectorUring.swift +++ b/Sources/NIOPosix/SelectorUring.swift @@ -219,9 +219,9 @@ extension Selector: _SelectorBackendProtocol { /// Apply the given `SelectorStrategy` and execute `body` once it's complete (which may produce `SelectorEvent`s to handle). /// - /// - parameters: - /// - strategy: The `SelectorStrategy` to apply - /// - body: The function to execute for each `SelectorEvent` that was produced. + /// - Parameters: + /// - strategy: The `SelectorStrategy` to apply + /// - body: The function to execute for each `SelectorEvent` that was produced. func whenReady0( strategy: SelectorStrategy, onLoopBegin loopStart: () -> Void, diff --git a/Sources/NIOPosix/ServerSocket.swift b/Sources/NIOPosix/ServerSocket.swift index 153bd36692..e75b99c205 100644 --- a/Sources/NIOPosix/ServerSocket.swift +++ b/Sources/NIOPosix/ServerSocket.swift @@ -32,12 +32,12 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// Create a new instance. /// - /// - parameters: - /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). - /// - protocolSubtype: The subtype of the protocol, corresponding to the `protocol` + /// - Parameters: + /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). + /// - protocolSubtype: The subtype of the protocol, corresponding to the `protocol` /// argument to the socket syscall. Defaults to 0. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if creation of the socket failed. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if creation of the socket failed. init( protocolFamily: NIOBSDSocket.ProtocolFamily, protocolSubtype: NIOBSDSocket.ProtocolSubtype = .default, @@ -60,10 +60,10 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// Create a new instance. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound socket. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if socket is invalid. + /// - Parameters: + /// - descriptor: The _Unix file descriptor_ representing the bound socket. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if socket is invalid. #if !os(Windows) @available(*, deprecated, renamed: "init(socket:setNonBlocking:)") convenience init(descriptor: CInt, setNonBlocking: Bool = false) throws { @@ -73,10 +73,10 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// Create a new instance. /// - /// - parameters: - /// - descriptor: The _Unix file descriptor_ representing the bound socket. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if socket is invalid. + /// - Parameters: + /// - descriptor: The _Unix file descriptor_ representing the bound socket. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if socket is invalid. init(socket: NIOBSDSocket.Handle, setNonBlocking: Bool = false) throws { cleanupOnClose = false // socket already bound, owner must clean up try super.init(socket: socket) @@ -87,9 +87,9 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// Start to listen for new connections. /// - /// - parameters: - /// - backlog: The backlog to use. - /// - throws: An `IOError` if creation of the socket failed. + /// - Parameters: + /// - backlog: The backlog to use. + /// - Throws: An `IOError` if creation of the socket failed. func listen(backlog: Int32 = 128) throws { try withUnsafeHandle { _ = try NIOBSDSocket.listen(socket: $0, backlog: backlog) @@ -98,10 +98,10 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// Accept a new connection /// - /// - parameters: - /// - setNonBlocking: set non-blocking mode on the returned `Socket`. On Linux this will use accept4 with SOCK_NONBLOCK to save a system call. - /// - returns: A `Socket` once a new connection was established or `nil` if this `ServerSocket` is in non-blocking mode and there is no new connection that can be accepted when this method is called. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - setNonBlocking: set non-blocking mode on the returned `Socket`. On Linux this will use accept4 with SOCK_NONBLOCK to save a system call. + /// - Returns: A `Socket` once a new connection was established or `nil` if this `ServerSocket` is in non-blocking mode and there is no new connection that can be accepted when this method is called. + /// - Throws: An `IOError` if the operation failed. func accept(setNonBlocking: Bool = false) throws -> Socket? { try withUnsafeHandle { fd in #if os(Linux) @@ -141,7 +141,7 @@ class ServerSocket: BaseSocket, ServerSocketProtocol { /// /// After the socket was closed all other methods will throw an `IOError` when called. /// - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. override func close() throws { let maybePathname = self.cleanupOnClose ? (try? self.localAddress().pathname) : nil try super.close() diff --git a/Sources/NIOPosix/Socket.swift b/Sources/NIOPosix/Socket.swift index 450c3a6173..1535e42d03 100644 --- a/Sources/NIOPosix/Socket.swift +++ b/Sources/NIOPosix/Socket.swift @@ -29,13 +29,13 @@ class Socket: BaseSocket, SocketProtocol { /// Create a new instance. /// - /// - parameters: - /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). - /// - type: The type of the socket to create. - /// - protocolSubtype: The subtype of the protocol, corresponding to the `protocolSubtype` + /// - Parameters: + /// - protocolFamily: The protocol family to use (usually `AF_INET6` or `AF_INET`). + /// - type: The type of the socket to create. + /// - protocolSubtype: The subtype of the protocol, corresponding to the `protocolSubtype` /// argument to the socket syscall. Defaults to 0. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if creation of the socket failed. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if creation of the socket failed. init( protocolFamily: NIOBSDSocket.ProtocolFamily, type: NIOBSDSocket.SocketType, @@ -53,10 +53,10 @@ class Socket: BaseSocket, SocketProtocol { /// Create a new instance out of an already established socket. /// - /// - parameters: - /// - descriptor: The existing socket descriptor. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if could not change the socket into non-blocking + /// - Parameters: + /// - descriptor: The existing socket descriptor. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if could not change the socket into non-blocking #if !os(Windows) @available(*, deprecated, renamed: "init(socket:setNonBlocking:)") convenience init(descriptor: CInt, setNonBlocking: Bool) throws { @@ -66,10 +66,10 @@ class Socket: BaseSocket, SocketProtocol { /// Create a new instance out of an already established socket. /// - /// - parameters: - /// - descriptor: The existing socket descriptor. - /// - setNonBlocking: Set non-blocking mode on the socket. - /// - throws: An `IOError` if could not change the socket into non-blocking + /// - Parameters: + /// - descriptor: The existing socket descriptor. + /// - setNonBlocking: Set non-blocking mode on the socket. + /// - Throws: An `IOError` if could not change the socket into non-blocking init(socket: NIOBSDSocket.Handle, setNonBlocking: Bool) throws { try super.init(socket: socket) if setNonBlocking { @@ -82,8 +82,8 @@ class Socket: BaseSocket, SocketProtocol { /// The ownership of the passed in descriptor is transferred to this class. A user must call `close` to close the underlying /// file descriptor once it's not needed / used anymore. /// - /// - parameters: - /// - descriptor: The file descriptor to wrap. + /// - Parameters: + /// - descriptor: The file descriptor to wrap. #if !os(Windows) @available(*, deprecated, renamed: "init(socket:)") convenience init(descriptor: CInt) throws { @@ -96,18 +96,18 @@ class Socket: BaseSocket, SocketProtocol { /// The ownership of the passed in descriptor is transferred to this class. A user must call `close` to close the underlying /// file descriptor once it's not needed / used anymore. /// - /// - parameters: - /// - descriptor: The file descriptor to wrap. + /// - Parameters: + /// - descriptor: The file descriptor to wrap. override init(socket: NIOBSDSocket.Handle) throws { try super.init(socket: socket) } /// Connect to the `SocketAddress`. /// - /// - parameters: - /// - address: The `SocketAddress` to which the connection should be established. - /// - returns: `true` if the connection attempt completes, `false` if `finishConnect` must be called later to complete the connection attempt. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - address: The `SocketAddress` to which the connection should be established. + /// - Returns: `true` if the connection attempt completes, `false` if `finishConnect` must be called later to complete the connection attempt. + /// - Throws: An `IOError` if the operation failed. func connect(to address: SocketAddress) throws -> Bool { try withUnsafeHandle { fd in try address.withSockAddr { (ptr, size) in @@ -134,7 +134,7 @@ class Socket: BaseSocket, SocketProtocol { /// Finish a previous non-blocking `connect` operation. /// - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. func finishConnect() throws { let result: Int32 = try getOption(level: .socket, name: .so_error) if result != 0 { @@ -144,10 +144,10 @@ class Socket: BaseSocket, SocketProtocol { /// Write data to the remote peer. /// - /// - parameters: - /// - pointer: Pointer (and size) to data to write. - /// - returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - pointer: Pointer (and size) to data to write. + /// - Returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func write(pointer: UnsafeRawBufferPointer) throws -> IOResult { try withUnsafeHandle { try NIOBSDSocket.send( @@ -160,10 +160,10 @@ class Socket: BaseSocket, SocketProtocol { /// Write data to the remote peer (gathering writes). /// - /// - parameters: - /// - iovecs: The `IOVector`s to write. - /// - returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - iovecs: The `IOVector`s to write. + /// - Returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func writev(iovecs: UnsafeBufferPointer) throws -> IOResult { try withUnsafeHandle { try Posix.writev(descriptor: $0, iovecs: iovecs) @@ -172,14 +172,14 @@ class Socket: BaseSocket, SocketProtocol { /// Send data to a destination. /// - /// - parameters: - /// - pointer: Pointer (and size) to the data to send. - /// - destinationPtr: The destination to which the data should be sent. - /// - destinationSize: The size of the destination address given. - /// - controlBytes: Extra `cmsghdr` information. - /// - returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written + /// - Parameters: + /// - pointer: Pointer (and size) to the data to send. + /// - destinationPtr: The destination to which the data should be sent. + /// - destinationSize: The size of the destination address given. + /// - controlBytes: Extra `cmsghdr` information. + /// - Returns: The `IOResult` which indicates how much data could be written and if the operation returned before all could be written /// (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. func sendmsg( pointer: UnsafeRawBufferPointer, destinationPtr: UnsafePointer?, @@ -232,10 +232,10 @@ class Socket: BaseSocket, SocketProtocol { /// Read data from the socket. /// - /// - parameters: - /// - pointer: The pointer (and size) to the storage into which the data should be read. - /// - returns: The `IOResult` which indicates how much data could be read and if the operation returned before all could be read (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - pointer: The pointer (and size) to the storage into which the data should be read. + /// - Returns: The `IOResult` which indicates how much data could be read and if the operation returned before all could be read (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func read(pointer: UnsafeMutableRawBufferPointer) throws -> IOResult { try withUnsafeHandle { try Posix.read(descriptor: $0, pointer: pointer.baseAddress!, size: pointer.count) @@ -244,14 +244,14 @@ class Socket: BaseSocket, SocketProtocol { /// Receive data from the socket, along with aditional control information. /// - /// - parameters: - /// - pointer: The pointer (and size) to the storage into which the data should be read. - /// - storage: The address from which the data was received - /// - storageLen: The size of the storage itself. - /// - controlBytes: A buffer in memory for use receiving control bytes. This parameter will be modified to hold any data actually received. - /// - returns: The `IOResult` which indicates how much data could be received and if the operation returned before all the data could be received + /// - Parameters: + /// - pointer: The pointer (and size) to the storage into which the data should be read. + /// - storage: The address from which the data was received + /// - storageLen: The size of the storage itself. + /// - controlBytes: A buffer in memory for use receiving control bytes. This parameter will be modified to hold any data actually received. + /// - Returns: The `IOResult` which indicates how much data could be received and if the operation returned before all the data could be received /// (because the socket is in non-blocking mode) - /// - throws: An `IOError` if the operation failed. + /// - Throws: An `IOError` if the operation failed. func recvmsg( pointer: UnsafeMutableRawBufferPointer, storage: inout sockaddr_storage, @@ -316,12 +316,12 @@ class Socket: BaseSocket, SocketProtocol { /// Send the content of a file descriptor to the remote peer (if possible a zero-copy strategy is applied). /// - /// - parameters: - /// - fd: The file descriptor of the file to send. - /// - offset: The offset in the file. - /// - count: The number of bytes to send. - /// - returns: The `IOResult` which indicates how much data could be send and if the operation returned before all could be send (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - fd: The file descriptor of the file to send. + /// - offset: The offset in the file. + /// - count: The number of bytes to send. + /// - Returns: The `IOResult` which indicates how much data could be send and if the operation returned before all could be send (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func sendFile(fd: CInt, offset: Int, count: Int) throws -> IOResult { try withUnsafeHandle { try NIOBSDSocket.sendfile( @@ -335,10 +335,10 @@ class Socket: BaseSocket, SocketProtocol { /// Receive `MMsgHdr`s. /// - /// - parameters: - /// - msgs: The pointer to the `MMsgHdr`s into which the received message will be stored. - /// - returns: The `IOResult` which indicates how many messages could be received and if the operation returned before all messages could be received (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - msgs: The pointer to the `MMsgHdr`s into which the received message will be stored. + /// - Returns: The `IOResult` which indicates how many messages could be received and if the operation returned before all messages could be received (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func recvmmsg(msgs: UnsafeMutableBufferPointer) throws -> IOResult { try withUnsafeHandle { try NIOBSDSocket.recvmmsg( @@ -353,10 +353,10 @@ class Socket: BaseSocket, SocketProtocol { /// Send `MMsgHdr`s. /// - /// - parameters: - /// - msgs: The pointer to the `MMsgHdr`s which will be send. - /// - returns: The `IOResult` which indicates how many messages could be send and if the operation returned before all messages could be send (because the socket is in non-blocking mode). - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - msgs: The pointer to the `MMsgHdr`s which will be send. + /// - Returns: The `IOResult` which indicates how many messages could be send and if the operation returned before all messages could be send (because the socket is in non-blocking mode). + /// - Throws: An `IOError` if the operation failed. func sendmmsg(msgs: UnsafeMutableBufferPointer) throws -> IOResult { try withUnsafeHandle { try NIOBSDSocket.sendmmsg( @@ -370,9 +370,9 @@ class Socket: BaseSocket, SocketProtocol { /// Shutdown the socket. /// - /// - parameters: - /// - how: the mode of `Shutdown`. - /// - throws: An `IOError` if the operation failed. + /// - Parameters: + /// - how: the mode of `Shutdown`. + /// - Throws: An `IOError` if the operation failed. func shutdown(how: Shutdown) throws { try withUnsafeHandle { try NIOBSDSocket.shutdown(socket: $0, how: how) diff --git a/Sources/NIOPosix/SocketChannel.swift b/Sources/NIOPosix/SocketChannel.swift index 9ef4634d6c..245d880dda 100644 --- a/Sources/NIOPosix/SocketChannel.swift +++ b/Sources/NIOPosix/SocketChannel.swift @@ -48,7 +48,7 @@ extension ByteBuffer { /// A `Channel` for a client socket. /// -/// - note: All operations on `SocketChannel` are thread-safe. +/// - Note: All operations on `SocketChannel` are thread-safe. final class SocketChannel: BaseStreamSocketChannel { private var connectTimeout: TimeAmount? = nil @@ -190,7 +190,7 @@ final class SocketChannel: BaseStreamSocketChannel { /// A `Channel` for a server socket. /// -/// - note: All operations on `ServerSocketChannel` are thread-safe. +/// - Note: All operations on `ServerSocketChannel` are thread-safe. final class ServerSocketChannel: BaseSocketChannel { private var backlog: Int32 = 128 @@ -1022,10 +1022,10 @@ extension DatagramChannel: MulticastChannel { /// Given a socket option level, returns the appropriate socket option name for /// this group operation. /// - /// - parameters: - /// - level: The socket option level. Must be one of `IPPROTO_IP` or + /// - Parameters: + /// - level: The socket option level. Must be one of `IPPROTO_IP` or /// `IPPROTO_IPV6`. Will trap if an invalid value is provided. - /// - returns: The socket option name to use for this group operation. + /// - Returns: The socket option name to use for this group operation. func optionName(level: NIOBSDSocket.OptionLevel) -> NIOBSDSocket.Option { switch (self, level) { case (.join, .ip): diff --git a/Sources/NIOPosix/Thread.swift b/Sources/NIOPosix/Thread.swift index 1a5a9667ff..f61ab29e1d 100644 --- a/Sources/NIOPosix/Thread.swift +++ b/Sources/NIOPosix/Thread.swift @@ -52,7 +52,7 @@ final class NIOThread { /// Create a new instance /// /// - arguments: - /// - handle: The `ThreadOpsSystem.ThreadHandle` that is wrapped and used by the `NIOThread`. + /// - handle: The `ThreadOpsSystem.ThreadHandle` that is wrapped and used by the `NIOThread`. internal init(handle: ThreadOpsSystem.ThreadHandle, desiredName: String?) { self.handle = handle self.desiredName = desiredName @@ -62,9 +62,9 @@ final class NIOThread { /// /// - warning: Do not escape `pthread_t` from the closure for later use. /// - /// - parameters: - /// - body: The closure that will accept the `pthread_t`. - /// - returns: The value returned by `body`. + /// - Parameters: + /// - body: The closure that will accept the `pthread_t`. + /// - Returns: The value returned by `body`. internal func withUnsafeThreadHandle(_ body: (ThreadOpsSystem.ThreadHandle) throws -> T) rethrows -> T { try body(self.handle) } @@ -81,9 +81,9 @@ final class NIOThread { /// Spawns and runs some task in a `NIOThread`. /// /// - arguments: - /// - name: The name of the `NIOThread` or `nil` if no specific name should be set. - /// - body: The function to execute within the spawned `NIOThread`. - /// - detach: Whether to detach the thread. If the thread is not detached it must be `join`ed. + /// - name: The name of the `NIOThread` or `nil` if no specific name should be set. + /// - body: The function to execute within the spawned `NIOThread`. + /// - detach: Whether to detach the thread. If the thread is not detached it must be `join`ed. static func spawnAndRun( name: String? = nil, detachThread: Bool = true, @@ -187,7 +187,7 @@ public final class ThreadSpecificVariable { /// Initialize a new `ThreadSpecificVariable` with `value` for the calling thread. After calling this, the calling /// thread will see `currentValue == value` but on all other threads `currentValue` will be `nil` until changed. /// - /// - parameters: + /// - Parameters: /// - value: The value to set for the calling thread. public convenience init(value: Value) { self.init() diff --git a/Sources/NIOPosix/VsockAddress.swift b/Sources/NIOPosix/VsockAddress.swift index 94d0f797d6..40b33673ae 100644 --- a/Sources/NIOPosix/VsockAddress.swift +++ b/Sources/NIOPosix/VsockAddress.swift @@ -44,10 +44,9 @@ public struct VsockAddress: Hashable, Sendable { /// Creates a new vsock address. /// - /// - parameters: + /// - Parameters: /// - cid: the context ID. /// - port: the target port. - /// - returns: the address for the given context ID and port combination. public init(cid: ContextID, port: Port) { self.cid = cid self.port = port diff --git a/Sources/NIOTestUtils/EventCounterHandler.swift b/Sources/NIOTestUtils/EventCounterHandler.swift index 7b82293be9..b5fa3ffb2a 100644 --- a/Sources/NIOTestUtils/EventCounterHandler.swift +++ b/Sources/NIOTestUtils/EventCounterHandler.swift @@ -22,7 +22,7 @@ import NIOCore /// Adding `EventCounterHandler` to any point of your `ChannelPipeline` should not change the program's behaviour. /// `EventCounterHandler` is mostly useful in unit tests to validate other `ChannelHandler`'s behaviour. /// -/// - note: Contrary to most `ChannelHandler`s, all of `EventCounterHandler`'s API is thread-safe meaning that you can +/// - Note: Contrary to most `ChannelHandler`s, all of `EventCounterHandler`'s API is thread-safe meaning that you can /// query the events received from any thread. public final class EventCounterHandler: Sendable { private let _channelRegisteredCalls = ManagedAtomic(0) @@ -149,7 +149,7 @@ extension EventCounterHandler { /// `register` event and you call `checkValidity`, it will throw `EventCounterHandler.ValidityError` with an /// appropriate explanation. /// - /// - note: This API is thread-safe, you may call it from any thread. The results of this API may vary though if you + /// - Note: This API is thread-safe, you may call it from any thread. The results of this API may vary though if you /// call it whilst the `Channel` this `ChannelHandler` is in is still in use. public func checkValidity() throws { guard self.channelRegisteredCalls <= 1 else { @@ -179,7 +179,7 @@ extension EventCounterHandler { /// /// This is most useful in unit tests where you want to make sure only certain events have been triggered. /// - /// - note: This API is thread-safe, you may call it from any thread. The results of this API may vary though if you + /// - Note: This API is thread-safe, you may call it from any thread. The results of this API may vary though if you /// call it whilst the `Channel` this `ChannelHandler` is in is still in use. public func allTriggeredEvents() -> Set { var allEvents: Set = [] diff --git a/Sources/NIOWebSocket/NIOWebSocketServerUpgrader.swift b/Sources/NIOWebSocket/NIOWebSocketServerUpgrader.swift index 2ac03cf2a4..8aa16eec7c 100644 --- a/Sources/NIOWebSocket/NIOWebSocketServerUpgrader.swift +++ b/Sources/NIOWebSocket/NIOWebSocketServerUpgrader.swift @@ -83,16 +83,16 @@ public final class NIOWebSocketServerUpgrader: HTTPServerProtocolUpgrader, @unch /// Create a new `NIOWebSocketServerUpgrader`. /// - /// - parameters: - /// - automaticErrorHandling: Whether the pipeline should automatically handle protocol + /// - Parameters: + /// - automaticErrorHandling: Whether the pipeline should automatically handle protocol /// errors by sending error responses and closing the connection. Defaults to `true`, /// may be set to `false` if the user wishes to handle their own errors. - /// - shouldUpgrade: A callback that determines whether the websocket request should be + /// - shouldUpgrade: A callback that determines whether the websocket request should be /// upgraded. This callback is responsible for creating a `HTTPHeaders` object with /// any headers that it needs on the response *except for* the `Upgrade`, `Connection`, /// and `Sec-WebSocket-Accept` headers, which this upgrader will handle. Should return /// an `EventLoopFuture` containing `nil` if the upgrade should be refused. - /// - upgradePipelineHandler: A function that will be called once the upgrade response is + /// - upgradePipelineHandler: A function that will be called once the upgrade response is /// flushed, and that is expected to mutate the `Channel` appropriately to handle the /// websocket protocol. This only needs to add the user handlers: the /// `WebSocketFrameEncoder` and `WebSocketFrameDecoder` will have been added to the @@ -113,20 +113,20 @@ public final class NIOWebSocketServerUpgrader: HTTPServerProtocolUpgrader, @unch /// Create a new `NIOWebSocketServerUpgrader`. /// - /// - parameters: - /// - maxFrameSize: The maximum frame size the decoder is willing to tolerate from the + /// - Parameters: + /// - maxFrameSize: The maximum frame size the decoder is willing to tolerate from the /// remote peer. WebSockets in principle allows frame sizes up to `2**64` bytes, but /// this is an objectively unreasonable maximum value (on AMD64 systems it is not /// possible to even. Users may set this to any value up to `UInt32.max`. - /// - automaticErrorHandling: Whether the pipeline should automatically handle protocol + /// - automaticErrorHandling: Whether the pipeline should automatically handle protocol /// errors by sending error responses and closing the connection. Defaults to `true`, /// may be set to `false` if the user wishes to handle their own errors. - /// - shouldUpgrade: A callback that determines whether the websocket request should be + /// - shouldUpgrade: A callback that determines whether the websocket request should be /// upgraded. This callback is responsible for creating a `HTTPHeaders` object with /// any headers that it needs on the response *except for* the `Upgrade`, `Connection`, /// and `Sec-WebSocket-Accept` headers, which this upgrader will handle. Should return /// an `EventLoopFuture` containing `nil` if the upgrade should be refused. - /// - upgradePipelineHandler: A function that will be called once the upgrade response is + /// - upgradePipelineHandler: A function that will be called once the upgrade response is /// flushed, and that is expected to mutate the `Channel` appropriately to handle the /// websocket protocol. This only needs to add the user handlers: the /// `WebSocketFrameEncoder` and `WebSocketFrameDecoder` will have been added to the @@ -220,7 +220,7 @@ public final class NIOTypedWebSocketServerUpgrader: NIO /// remote peer. WebSockets in principle allows frame sizes up to `2**64` bytes, but /// this is an objectively unreasonable maximum value (on AMD64 systems it is not /// possible to even. Users may set this to any value up to `UInt32.max`. - /// - automaticErrorHandling: Whether the pipeline should automatically handle protocol + /// - enableAutomaticErrorHandling: Whether the pipeline should automatically handle protocol /// errors by sending error responses and closing the connection. Defaults to `true`, /// may be set to `false` if the user wishes to handle their own errors. /// - shouldUpgrade: A callback that determines whether the websocket request should be @@ -228,11 +228,9 @@ public final class NIOTypedWebSocketServerUpgrader: NIO /// any headers that it needs on the response *except for* the `Upgrade`, `Connection`, /// and `Sec-WebSocket-Accept` headers, which this upgrader will handle. Should return /// an `EventLoopFuture` containing `nil` if the upgrade should be refused. - /// - enableAutomaticErrorHandling: A function that will be called once the upgrade response is - /// flushed, and that is expected to mutate the `Channel` appropriately to handle the - /// websocket protocol. This only needs to add the user handlers: the /// `WebSocketFrameEncoder` and `WebSocketFrameDecoder` will have been added to the - /// pipeline automatically. + /// pipeline automatically.to WebSocket protocol errors. Default is true. + /// - upgradePipelineHandler: called once the upgrade was successful. public init( maxFrameSize: Int = 1 << 14, enableAutomaticErrorHandling: Bool = true, diff --git a/Sources/NIOWebSocket/SHA1.swift b/Sources/NIOWebSocket/SHA1.swift index bb7e4ed7e4..34cee4ce56 100644 --- a/Sources/NIOWebSocket/SHA1.swift +++ b/Sources/NIOWebSocket/SHA1.swift @@ -42,8 +42,8 @@ internal struct SHA1 { /// Feed the given string into the hash context as a sequence of UTF-8 bytes. /// - /// - parameters: - /// - string: The string that will be UTF-8 encoded and fed into the + /// - Parameters: + /// - string: The string that will be UTF-8 encoded and fed into the /// hash context. mutating func update(string: String) { let isAvailable: ()? = string.utf8.withContiguousStorageIfAvailable { @@ -60,15 +60,15 @@ internal struct SHA1 { /// Feed the bytes into the hash context. /// - /// - parameters: - /// - bytes: The bytes to feed into the hash context. + /// - Parameters: + /// - bytes: The bytes to feed into the hash context. mutating func update(_ bytes: UnsafeBufferPointer) { c_nio_sha1_loop(&self.sha1Ctx, bytes.baseAddress!, bytes.count) } /// Complete the hashing. /// - /// - returns: A 20-byte array of bytes. + /// - Returns: A 20-byte array of bytes. mutating func finish() -> [UInt8] { var hashResult: [UInt8] = Array(repeating: 0, count: 20) hashResult.withUnsafeMutableBufferPointer { diff --git a/Sources/NIOWebSocket/WebSocketErrorCodes.swift b/Sources/NIOWebSocket/WebSocketErrorCodes.swift index 2faf5bc915..296aac7928 100644 --- a/Sources/NIOWebSocket/WebSocketErrorCodes.swift +++ b/Sources/NIOWebSocket/WebSocketErrorCodes.swift @@ -85,7 +85,7 @@ public enum WebSocketErrorCode: Sendable { /// Create an error code from a raw 16-bit integer as sent on the /// network. /// - /// - parameters: + /// - Parameters: /// integer: The integer form of the status code. internal init(networkInteger integer: UInt16) { switch integer { @@ -116,8 +116,8 @@ public enum WebSocketErrorCode: Sendable { /// /// Will trap if the error code is not in the valid range. /// - /// - parameters: - /// - codeNumber: The integer form of the status code. + /// - Parameters: + /// - codeNumber: The integer form of the status code. public init(codeNumber: Int) { self.init(networkInteger: UInt16(codeNumber)) } @@ -130,7 +130,7 @@ extension ByteBuffer { /// /// This method increments the reader index. /// - /// - returns: The error code, or `nil` if there were not enough readable bytes. + /// - Returns: The error code, or `nil` if there were not enough readable bytes. public mutating func readWebSocketErrorCode() -> WebSocketErrorCode? { self.readInteger(as: UInt16.self).map { WebSocketErrorCode(networkInteger: $0) } } @@ -140,17 +140,17 @@ extension ByteBuffer { /// This method does not increment the reader index, and may be used to read an error /// code from outside the readable range of bytes. /// - /// - parameters: - /// - index: The index into the buffer to read the error code from. - /// - returns: The error code, or `nil` if there were not enough bytes at that index. + /// - Parameters: + /// - index: The index into the buffer to read the error code from. + /// - Returns: The error code, or `nil` if there were not enough bytes at that index. public func getWebSocketErrorCode(at index: Int) -> WebSocketErrorCode? { self.getInteger(at: index, as: UInt16.self).map { WebSocketErrorCode(networkInteger: $0) } } /// Write the given error code to the buffer. /// - /// - parameters: - /// - code: The code to write into the buffer. + /// - Parameters: + /// - code: The code to write into the buffer. public mutating func write(webSocketErrorCode code: WebSocketErrorCode) { self.writeInteger(UInt16(webSocketErrorCode: code)) } @@ -159,8 +159,8 @@ extension ByteBuffer { extension UInt16 { /// Create a UInt16 corresponding to a given `WebSocketErrorCode`. /// - /// - parameters: - /// - code: The `WebSocketErrorCode`. + /// - Parameters: + /// - code: The `WebSocketErrorCode`. public init(webSocketErrorCode code: WebSocketErrorCode) { switch code { case .normalClosure: diff --git a/Sources/NIOWebSocket/WebSocketFrame.swift b/Sources/NIOWebSocket/WebSocketFrame.swift index 5fc4bd0e59..d6b8a1ff2f 100644 --- a/Sources/NIOWebSocket/WebSocketFrame.swift +++ b/Sources/NIOWebSocket/WebSocketFrame.swift @@ -53,8 +53,8 @@ public struct WebSocketMaskingKey: Sendable { /// Creates a websocket masking key from the network-encoded /// representation. /// - /// - parameters: - /// - integer: The encoded network representation of the + /// - Parameters: + /// - integer: The encoded network representation of the /// masking key. @usableFromInline internal init(networkRepresentation integer: UInt32) { @@ -290,23 +290,23 @@ public struct WebSocketFrame { /// Creates an empty `WebSocketFrame`. /// - /// - parameters: - /// - allocator: The `ByteBufferAllocator` to use when editing the empty buffers. + /// - Parameters: + /// - allocator: The `ByteBufferAllocator` to use when editing the empty buffers. public init(allocator: ByteBufferAllocator) { self._storage = .init(data: allocator.buffer(capacity: 0), extensionData: nil) } /// Create a `WebSocketFrame` with the given properties. /// - /// - parameters: - /// - fin: The value of the `fin` bit. Defaults to `false`. - /// - rsv1: The value of the first reserved bit. Defaults to `false`. - /// - rsv2: The value of the second reserved bit. Defaults to `false`. - /// - rsv3: The value of the third reserved bit. Defaults to `false`. - /// - opcode: The opcode for the frame. Defaults to `.continuation`. - /// - maskKey: The masking key for the frame, if any. Defaults to `nil`. - /// - data: The application data for the frame. - /// - extensionData: The extension data for the frame. + /// - Parameters: + /// - fin: The value of the `fin` bit. Defaults to `false`. + /// - rsv1: The value of the first reserved bit. Defaults to `false`. + /// - rsv2: The value of the second reserved bit. Defaults to `false`. + /// - rsv3: The value of the third reserved bit. Defaults to `false`. + /// - opcode: The opcode for the frame. Defaults to `.continuation`. + /// - maskKey: The masking key for the frame, if any. Defaults to `nil`. + /// - data: The application data for the frame. + /// - extensionData: The extension data for the frame. public init( fin: Bool = false, rsv1: Bool = false, @@ -383,7 +383,7 @@ extension WebSocketFrame: CustomStringConvertible { /// /// The format of the description is not API. /// - /// - returns: A description of this `WebSocketFrame`. + /// - Returns: A description of this `WebSocketFrame`. public var description: String { """ maskKey: \(String(describing: self.maskKey)), \ diff --git a/Sources/NIOWebSocket/WebSocketFrameDecoder.swift b/Sources/NIOWebSocket/WebSocketFrameDecoder.swift index 583cdbec66..ebd4030bfb 100644 --- a/Sources/NIOWebSocket/WebSocketFrameDecoder.swift +++ b/Sources/NIOWebSocket/WebSocketFrameDecoder.swift @@ -42,8 +42,12 @@ extension WebSocketErrorCode { extension ByteBuffer { /// Applies the WebSocket unmasking operation. /// - /// - parameters: - /// - maskingKey: The masking key. + /// - Parameters: + /// - maskingKey: The masking key. + /// - indexOffset: An integer offset to apply to the index into the masking key. + /// This is used when masking multiple "contiguous" byte buffers, to ensure that + /// the masking key is applied uniformly to the collection rather than from the + /// start each time. public mutating func webSocketUnmask(_ maskingKey: WebSocketMaskingKey, indexOffset: Int = 0) { /// Shhhh: secretly unmasking and masking are the same operation! webSocketMask(maskingKey, indexOffset: indexOffset) @@ -51,9 +55,9 @@ extension ByteBuffer { /// Applies the websocket masking operation. /// - /// - parameters: - /// - maskingKey: The masking key. - /// - indexOffset: An integer offset to apply to the index into the masking key. + /// - Parameters: + /// - maskingKey: The masking key. + /// - indexOffset: An integer offset to apply to the index into the masking key. /// This is used when masking multiple "contiguous" byte buffers, to ensure that /// the masking key is applied uniformly to the collection rather than from the /// start each time. @@ -237,8 +241,8 @@ public final class WebSocketFrameDecoder: ByteToMessageDecoder { /// Construct a new `WebSocketFrameDecoder` /// - /// - parameters: - /// - maxFrameSize: The maximum frame size the decoder is willing to tolerate from the + /// - Parameters: + /// - maxFrameSize: The maximum frame size the decoder is willing to tolerate from the /// remote peer. WebSockets in principle allows frame sizes up to `2**64` bytes, but /// this is an objectively unreasonable maximum value (on AMD64 systems it is not /// possible to even allocate a buffer large enough to handle this size), so we @@ -247,9 +251,6 @@ public final class WebSocketFrameDecoder: ByteToMessageDecoder { /// Users are strongly encouraged not to increase this value unless they absolutely /// must, as the decoder will not produce partial frames, meaning that it will hold /// on to data until the *entire* body is received. - /// - automaticErrorHandling: Whether this `ChannelHandler` should automatically handle - /// protocol errors in frame serialization, or whether it should allow the pipeline - /// to handle them. public init(maxFrameSize: Int = 1 << 14) { precondition(maxFrameSize <= UInt32.max, "invalid overlarge max frame size") self.maxFrameSize = maxFrameSize diff --git a/Sources/NIOWebSocket/WebSocketOpcode.swift b/Sources/NIOWebSocket/WebSocketOpcode.swift index 953d8c1b53..5979ab7571 100644 --- a/Sources/NIOWebSocket/WebSocketOpcode.swift +++ b/Sources/NIOWebSocket/WebSocketOpcode.swift @@ -27,8 +27,8 @@ public struct WebSocketOpcode: Sendable { /// Create an opcode from the encoded representation. /// - /// - parameters - /// - encoded: The encoded representation of the opcode as an 8-bit integer. + /// - Parameters + /// - encoded: The encoded representation of the opcode as an 8-bit integer. /// Must be no more than 4 bits large. public init?(encodedWebSocketOpcode encoded: UInt8) { guard encoded < 0x10 else { @@ -89,8 +89,8 @@ extension UInt8 { /// This places the opcode in the four least-significant bits, in /// a form suitable for sending on the wire. /// - /// - parameters: - /// - opcode: The `WebSocketOpcode`. + /// - Parameters: + /// - opcode: The `WebSocketOpcode`. public init(webSocketOpcode opcode: WebSocketOpcode) { precondition(opcode.networkRepresentation < 0x10) self = opcode.networkRepresentation @@ -100,8 +100,8 @@ extension UInt8 { extension Int { /// Create a UInt8 corresponding to the integer value for a given `WebSocketOpcode`. /// - /// - parameters: - /// - opcode: The `WebSocketOpcode`. + /// - Parameters: + /// - opcode: The `WebSocketOpcode`. public init(webSocketOpcode opcode: WebSocketOpcode) { precondition(opcode.networkRepresentation < 0x10) self = Int(opcode.networkRepresentation) diff --git a/Tests/NIOPosixTests/ChannelTests.swift b/Tests/NIOPosixTests/ChannelTests.swift index 6406f9a4ae..a1df4bee11 100644 --- a/Tests/NIOPosixTests/ChannelTests.swift +++ b/Tests/NIOPosixTests/ChannelTests.swift @@ -259,13 +259,13 @@ public final class ChannelTests: XCTestCase { /// /// The write operations will all be faked and return the return values provided in `returns`. /// - /// - parameters: - /// - pwm: The `PendingStreamWritesManager` to test. - /// - promises: The promises for the writes issued. - /// - expectedSingleWritabilities: The expected buffer lengths for the calls to the single write operation. - /// - expectedVectorWritabilities: The expected buffer lengths for the calls to the vector write operation. - /// - returns: The return values of the fakes write operations (both single and vector). - /// - promiseStates: The states of the promises _after_ the write operations are done. + /// - Parameters: + /// - pwm: The `PendingStreamWritesManager` to test. + /// - promises: The promises for the writes issued. + /// - expectedSingleWritabilities: The expected buffer lengths for the calls to the single write operation. + /// - expectedVectorWritabilities: The expected buffer lengths for the calls to the vector write operation. + /// - returns: The return values of the fakes write operations (both single and vector). + /// - promiseStates: The states of the promises _after_ the write operations are done. func assertExpectedWritability( pendingWritesManager pwm: PendingStreamWritesManager, promises: [EventLoopPromise], diff --git a/Tests/NIOPosixTests/PendingDatagramWritesManagerTests.swift b/Tests/NIOPosixTests/PendingDatagramWritesManagerTests.swift index 76bcb6db34..3ef944b19f 100644 --- a/Tests/NIOPosixTests/PendingDatagramWritesManagerTests.swift +++ b/Tests/NIOPosixTests/PendingDatagramWritesManagerTests.swift @@ -71,13 +71,13 @@ class PendingDatagramWritesManagerTests: XCTestCase { /// /// The write operations will all be faked and return the return values provided in `returns`. /// - /// - parameters: - /// - pwm: The `PendingStreamWritesManager` to test. - /// - promises: The promises for the writes issued. - /// - expectedSingleWritabilities: The expected buffer lengths and addresses for the calls to the single write operation. - /// - expectedVectorWritabilities: The expected buffer lengths and addresses for the calls to the vector write operation. - /// - returns: The return values of the fakes write operations (both single and vector). - /// - promiseStates: The states of the promises _after_ the write operations are done. + /// - Parameters: + /// - pwm: The `PendingStreamWritesManager` to test. + /// - promises: The promises for the writes issued. + /// - expectedSingleWritabilities: The expected buffer lengths and addresses for the calls to the single write operation. + /// - expectedVectorWritabilities: The expected buffer lengths and addresses for the calls to the vector write operation. + /// - returns: The return values of the fakes write operations (both single and vector). + /// - promiseStates: The states of the promises _after_ the write operations are done. private func assertExpectedWritability( pendingWritesManager pwm: PendingDatagramWritesManager, promises: [EventLoopPromise], diff --git a/Tests/NIOPosixTests/TestUtils.swift b/Tests/NIOPosixTests/TestUtils.swift index 1d34587f2e..c646379156 100644 --- a/Tests/NIOPosixTests/TestUtils.swift +++ b/Tests/NIOPosixTests/TestUtils.swift @@ -448,7 +448,7 @@ func assertFailure(_ result: Result, file: StaticString = # /// Fulfills the promise when the respective event is first received. /// -/// - note: Once this is used more widely and shows value, we might want to put it into `NIOTestUtils`. +/// - Note: Once this is used more widely and shows value, we might want to put it into `NIOTestUtils`. final class FulfillOnFirstEventHandler: ChannelDuplexHandler { typealias InboundIn = Any typealias OutboundIn = Any diff --git a/docs/public-async-nio-apis.md b/docs/public-async-nio-apis.md index 2a3ff118c1..60f80ac904 100644 --- a/docs/public-async-nio-apis.md +++ b/docs/public-async-nio-apis.md @@ -676,22 +676,22 @@ final public class NIOTypedHTTPClientUpgradeHandler : NIOCore.Cha /// Called when this `ChannelHandler` is added to the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. public func handlerAdded(context: NIOCore.ChannelHandlerContext) /// Called when this `ChannelHandler` is removed from the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. public func handlerRemoved(context: NIOCore.ChannelHandlerContext) /// Called when the `Channel` has become active, and is able to send and receive data. /// /// This should call `context.fireChannelActive` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. public func channelActive(context: NIOCore.ChannelHandlerContext) /// Called to request a write operation. The write operation will write the messages through the @@ -701,19 +701,19 @@ final public class NIOTypedHTTPClientUpgradeHandler : NIOCore.Cha /// This should call `context.write` to forward the operation to the next `_ChannelOutboundHandler` in the `ChannelPipeline` or /// complete the `EventLoopPromise` to let the caller know that the operation completed. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - data: The data to write through the `Channel`, wrapped in a `NIOAny`. - /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - data: The data to write through the `Channel`, wrapped in a `NIOAny`. + /// - promise: The `EventLoopPromise` which should be notified once the operation completes, or nil if no notification should take place. public func write(context: NIOCore.ChannelHandlerContext, data: NIOCore.NIOAny, promise: NIOCore.EventLoopPromise?) /// Called when some data has been read from the remote peer. /// /// This should call `context.fireChannelRead` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - data: The data read from the remote peer, wrapped in a `NIOAny`. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - data: The data read from the remote peer, wrapped in a `NIOAny`. public func channelRead(context: NIOCore.ChannelHandlerContext, data: NIOCore.NIOAny) } @@ -795,23 +795,23 @@ final public class NIOTypedHTTPServerUpgradeHandler : NIOCore.Cha /// Called when this `ChannelHandler` is added to the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. public func handlerAdded(context: NIOCore.ChannelHandlerContext) /// Called when this `ChannelHandler` is removed from the `ChannelPipeline`. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. public func handlerRemoved(context: NIOCore.ChannelHandlerContext) /// Called when some data has been read from the remote peer. /// /// This should call `context.fireChannelRead` to forward the operation to the next `_ChannelInboundHandler` in the `ChannelPipeline` if you want to allow the next handler to also handle the event. /// - /// - parameters: - /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. - /// - data: The data read from the remote peer, wrapped in a `NIOAny`. + /// - Parameters: + /// - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to. + /// - data: The data read from the remote peer, wrapped in a `NIOAny`. public func channelRead(context: NIOCore.ChannelHandlerContext, data: NIOCore.NIOAny) } ``` @@ -960,40 +960,40 @@ final public class NIOTypedApplicationProtocolNegotiationHandler