Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Tweak formatting of function DocC comments #407

Merged
merged 1 commit into from
Jul 5, 2023
Merged

Tweak formatting of function DocC comments #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 21 additions & 16 deletions Sources/NIOHPACK/HPACKHeader.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ public struct HPACKHeaders: ExpressibleByDictionaryLiteral, Sendable {
/// The indexability of all headers is assumed to be the default, i.e. indexable and
/// rewritable by proxies.
///
/// - parameters
/// - headers: An initial set of headers to use to populate the header block.
/// - Parameters:
/// - headers: An initial set of headers to use to populate the header block.
@inlinable
public init(_ headers: [(String, String)] = []) {
self.headers = headers.map { HPACKHeader(name: $0.0, value: $0.1) }
Expand All @@ -104,9 +104,9 @@ public struct HPACKHeaders: ExpressibleByDictionaryLiteral, Sendable {
/// The indexability of all headers is assumed to be the default, i.e. indexable and
/// rewritable by proxies.
///
/// - 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.
@available(*, deprecated, renamed: "init(_:)")
public init(_ headers: [(String, String)] = [], allocator: ByteBufferAllocator) {
// We no longer use an allocator so we don't need this method anymore.
Expand All @@ -130,10 +130,12 @@ public struct HPACKHeaders: ExpressibleByDictionaryLiteral, Sendable {
/// This method is strictly additive: if there are other values for the given header name
/// already in the block, this will add a new entry. `add` performs case-insensitive
/// comparisons on the header field name.
///
/// - Parameter name: The header field name. This must be an ASCII string. For HTTP/2 lowercase
/// header names are strongly encouraged.
/// - Parameter value: The header field value to add for the given name.
/// - Parameters:
/// - name: The header field name. This must be an ASCII string. For HTTP/2 lowercase
/// header names are strongly encouraged.
/// - value: The header field value to add for the given name.
/// - indexing: The types of indexing and rewriting operations a decoder may take with
/// regard to this header.
@inlinable
public mutating func add(name: String, value: String, indexing: HPACKIndexing = .indexable) {
precondition(!name.utf8.contains(where: { !$0.isASCII }), "name must be ASCII")
Expand Down Expand Up @@ -179,10 +181,13 @@ public struct HPACKHeaders: ExpressibleByDictionaryLiteral, Sendable {
/// Like `add`, this method performs case-insensitive comparisons of the header field
/// names.
///
/// - Parameter name: The header field name. For maximum compatibility this should be an
/// ASCII string. For future-proofing with HTTP/2 lowercase header names are strongly
/// recommended.
/// - Parameter value: The header field value to add for the given name.
/// - Parameters:
/// - name: The header field name. For maximum compatibility this should be an
/// ASCII string. For future-proofing with HTTP/2 lowercase header names are strongly
/// recommended.
/// - value: The header field value to add for the given name.
/// - indexing: The types of indexing and rewriting operations a decoder may take with
/// regard to this header.
@inlinable
public mutating func replaceOrAdd(name: String, value: String, indexing: HPACKIndexing = .indexable) {
self.remove(name: name)
Expand Down Expand Up @@ -239,9 +244,9 @@ public struct HPACKHeaders: ExpressibleByDictionaryLiteral, Sendable {

/// Checks if a header is present.
///
/// - parameters:
/// - name: The name of the header
/// - returns: `true` if a header with the name (and value) exists, `false` otherwise.
/// - Parameters:
/// - name: The name of the header
/// - Returns: `true` if a header with the name (and value) exists, `false` otherwise.
@inlinable
public func contains(name: String) -> Bool {
guard !self.headers.isEmpty else {
Expand Down
6 changes: 3 additions & 3 deletions Sources/NIOHTTP2/ConnectionStateMachine/ConnectionStateMachine.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1612,9 +1612,9 @@ extension HTTP2ConnectionStateMachine {

/// Validates a single HTTP/2 settings block.
///
/// - parameters:
/// - settings: The HTTP/2 settings block to validate.
/// - returns: The result of the validation.
/// - Parameters:
/// - settings: The HTTP/2 settings block to validate.
/// - Returns: The result of the validation.
private func validateSettings(_ settings: HTTP2Settings) -> StateMachineResult {
for setting in settings {
switch setting.parameter {
Expand Down
68 changes: 34 additions & 34 deletions Sources/NIOHTTP2/ConnectionStateMachine/ConnectionStreamsState.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,10 @@ struct ConnectionStreamState {
/// Unlike with idle streams, which are served by `modifyStreamStateCreateIfNeeded`, for pushed streams we do not
/// have to perform a modification operation. For this reason, we can use a simpler control flow.
///
/// - parameters:
/// - streamID: The ID of the pushed stream.
/// - remoteInitialWindowSize: The initial window size of the remote peer.
/// - requestVerb: the HTTP method used on the request
/// - Parameters:
/// - streamID: The ID of the pushed stream.
/// - remoteInitialWindowSize: The initial window size of the remote peer.
/// - requestVerb: the HTTP method used on the request
/// - throws: If the stream ID is invalid.
mutating func createRemotelyPushedStream(streamID: HTTP2StreamID, remoteInitialWindowSize: UInt32, requestVerb: String?) throws {
try self.reserveServerStreamID(streamID)
Expand All @@ -90,9 +90,9 @@ struct ConnectionStreamState {
/// Unlike with idle streams, which are served by `modifyStreamStateCreateIfNeeded`, for pushed streams we do not
/// have to perform a modification operation. For this reason, we can use a simpler control flow.
///
/// - parameters:
/// - streamID: The ID of the pushed stream.
/// - localInitialWindowSize: Our initial window size..
/// - Parameters:
/// - streamID: The ID of the pushed stream.
/// - localInitialWindowSize: Our initial window size..
/// - throws: If the stream ID is invalid.
mutating func createLocallyPushedStream(streamID: HTTP2StreamID, localInitialWindowSize: UInt32, requestVerb: String?) throws {
try self.reserveServerStreamID(streamID)
Expand All @@ -105,14 +105,14 @@ struct ConnectionStreamState {
/// The `creator` block will be called if the stream does not exist already. The `modifier` block will be called
/// if the stream was created, or if it was found in the map.
///
/// - parameters:
/// - streamID: The ID of the stream to modify.
/// - localRole: The connection role of the local peer.
/// - localInitialWindowSize: The initial size of the local flow control window for new streams.
/// - remoteInitialWindowSize: The initial size of the remote flow control window for new streams.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - Parameters:
/// - streamID: The ID of the stream to modify.
/// - localRole: The connection role of the local peer.
/// - localInitialWindowSize: The initial size of the local flow control window for new streams.
/// - remoteInitialWindowSize: The initial size of the remote flow control window for new streams.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - throws: Any errors thrown from the creator.
/// - returns: The result of the state modification, as well as any state change that occurred to the stream.
/// - Returns: The result of the state modification, as well as any state change that occurred to the stream.
mutating func modifyStreamStateCreateIfNeeded(streamID: HTTP2StreamID,
localRole: HTTP2StreamStateMachine.StreamRole,
localInitialWindowSize: UInt32,
Expand Down Expand Up @@ -152,12 +152,12 @@ struct ConnectionStreamState {
/// The block will be called so long as the stream exists in the currently active streams. If it does not, we will check
/// whether the stream has been closed already.
///
/// - parameters:
/// - streamID: The ID of the stream to modify.
/// - ignoreRecentlyReset: Whether a recently reset stream should be ignored. Should be set to `true` when receiving frames.
/// - ignoreClosed: Whether a closed stream should be ignored. Should be set to `true` when receiving window update or reset stream frames.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - returns: The result of the state modification, as well as any state change that occurred to the stream.
/// - Parameters:
/// - streamID: The ID of the stream to modify.
/// - ignoreRecentlyReset: Whether a recently reset stream should be ignored. Should be set to `true` when receiving frames.
/// - ignoreClosed: Whether a closed stream should be ignored. Should be set to `true` when receiving window update or reset stream frames.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - Returns: The result of the state modification, as well as any state change that occurred to the stream.
mutating func modifyStreamState(streamID: HTTP2StreamID,
ignoreRecentlyReset: Bool,
ignoreClosed: Bool = false,
Expand All @@ -180,10 +180,10 @@ struct ConnectionStreamState {
///
/// This block must close the stream. Failing to do so is a programming error.
///
/// - parameters:
/// - streamID: The ID of the stream to modify.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - returns: The result of the state modification, as well as any state change that occurred to the stream.
/// - Parameters:
/// - streamID: The ID of the stream to modify.
/// - modifier: A block that will be invoked to modify the stream state, if present.
/// - Returns: The result of the state modification, as well as any state change that occurred to the stream.
@inline(__always)
mutating func locallyResetStreamState(streamID: HTTP2StreamID,
_ modifier: (inout HTTP2StreamStateMachine) -> StateMachineResultWithStreamEffect) -> StateMachineResultWithStreamEffect {
Expand Down Expand Up @@ -249,11 +249,11 @@ struct ConnectionStreamState {

/// Drop all streams with stream IDs larger than the given stream ID that were initiated by the given role.
///
/// - parameters:
/// - streamID: The last stream ID the remote peer is promising to handle.
/// - droppedLocally: Whether this drop was caused by sending a GOAWAY frame or receiving it.
/// - initiator: The peer that sent the GOAWAY frame.
/// - returns: the stream IDs closed by this operation.
/// - Parameters:
/// - streamID: The last stream ID the remote peer is promising to handle.
/// - droppedLocally: Whether this drop was caused by sending a GOAWAY frame or receiving it.
/// - initiator: The peer that sent the GOAWAY frame.
/// - Returns: the stream IDs closed by this operation.
mutating func dropAllStreamsWithIDHigherThan(_ streamID: HTTP2StreamID,
droppedLocally: Bool,
initiatedBy initiator: HTTP2ConnectionStateMachine.ConnectionRole) -> [HTTP2StreamID]? {
Expand Down Expand Up @@ -282,11 +282,11 @@ struct ConnectionStreamState {

/// Determines the state machine result to generate when we've been asked to modify a missing stream.
///
/// - parameters:
/// - streamID: The ID of the missing stream.
/// - ignoreRecentlyReset: Whether a recently reset stream should be ignored.
/// - ignoreClosed: Whether a closed stream should be ignored.
/// - returns: A `StateMachineResult` for this frame error.
/// - Parameters:
/// - streamID: The ID of the missing stream.
/// - ignoreRecentlyReset: Whether a recently reset stream should be ignored.
/// - ignoreClosed: Whether a closed stream should be ignored.
/// - Returns: A `StateMachineResult` for this frame error.
private func streamMissing(streamID: HTTP2StreamID, ignoreRecentlyReset: Bool, ignoreClosed: Bool) -> StateMachineResult {
if ignoreRecentlyReset && self.recentlyResetStreams.contains(streamID) {
return .ignoreFrame
Expand Down
20 changes: 10 additions & 10 deletions Sources/NIOHTTP2/ConnectionStateMachine/HTTP2SettingsState.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ struct HTTP2SettingsState {
///
/// This function assumes that settings have been validated by the state machine.
///
/// - parameters:
/// - settings: The settings to emit.
/// - Parameters:
/// - settings: The settings to emit.
mutating func emitSettings(_ settings: HTTP2Settings) {
self.unacknowlegedSettingsFrames.append(settings)
}
Expand All @@ -87,8 +87,8 @@ struct HTTP2SettingsState {
///
/// This applies the pending SETTINGS values. If there are no pending SETTINGS values, this will throw.
///
/// - parameters:
/// - onValueChange: A callback that will be invoked once for each setting change.
/// - Parameters:
/// - onValueChange: A callback that will be invoked once for each setting change.
mutating func receiveSettingsAck(onValueChange: OnValueChangeCallback) throws {
guard self.unacknowlegedSettingsFrames.count > 0 else {
throw NIOHTTP2Errors.receivedBadSettings()
Expand All @@ -103,9 +103,9 @@ struct HTTP2SettingsState {
///
/// We auto-ACK all SETTINGS, so this applies the settings immediately.
///
/// - parameters:
/// - settings: The received settings.
/// - onValueChange: A callback that will be invoked once for each setting change.
/// - Parameters:
/// - settings: The received settings.
/// - onValueChange: A callback that will be invoked once for each setting change.
mutating func receiveSettings(_ settings: HTTP2Settings, onValueChange: OnValueChangeCallback) rethrows {
return try self.applySettings(settings, onValueChange: onValueChange)
}
Expand All @@ -114,9 +114,9 @@ struct HTTP2SettingsState {
///
/// This function assumes that settings have been validated by the state machine.
///
/// - parameters:
/// - settings: The settings to apply.
/// - onValueChange: A callback that will be invoked once for each setting change.
/// - Parameters:
/// - settings: The settings to apply.
/// - onValueChange: A callback that will be invoked once for each setting change.
private mutating func applySettings(_ settings: HTTP2Settings, onValueChange: OnValueChangeCallback) rethrows {
for setting in settings {
let oldValue = self.currentSettingsValues.updateValue(setting._value, forKey: setting.parameter)
Expand Down
6 changes: 3 additions & 3 deletions Sources/NIOHTTP2/Frame Buffers/OutboundFlowControlBuffer.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -455,10 +455,10 @@ extension StreamMap where Element == StreamFlowControlState {
//
/// Apply a transform to a wrapped DataBuffer.
///
/// - parameters:
/// - body: A block that will modify the contained value in the
/// - Parameters:
/// - body: A block that will modify the contained value in the
/// optional, if there is one present.
/// - returns: Whether the value was present or not.
/// - Returns: Whether the value was present or not.
@discardableResult
fileprivate mutating func apply(streamID: HTTP2StreamID, _ body: (inout Element) -> Void) -> Bool {
return self.modify(streamID: streamID, body) != nil
Expand Down
16 changes: 8 additions & 8 deletions Sources/NIOHTTP2/HTTP2ChannelHandler+InlineStreamMultiplexer.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,10 +181,10 @@ extension NIOHTTP2Handler {
///
/// > Note: Resources for the stream will be freed after it has been closed.
///
/// - parameters:
/// - promise: An `EventLoopPromise` that will be succeeded with the new activated channel, or
/// - Parameters:
/// - promise: An `EventLoopPromise` that will be succeeded with the new activated channel, or
/// failed if an error occurs.
/// - streamStateInitializer: A callback that will be invoked to allow you to configure the
/// - streamStateInitializer: A callback that will be invoked to allow you to configure the
/// `ChannelPipeline` for the newly created channel.
public func createStreamChannel(promise: EventLoopPromise<Channel>?, _ streamStateInitializer: @escaping StreamInitializer) {
self.inlineStreamMultiplexer.createStreamChannel(promise: promise, streamStateInitializer)
Expand Down Expand Up @@ -247,15 +247,15 @@ extension NIOHTTP2Handler {
/// Create a stream channel initialized with the provided closure and return it wrapped within a `NIOAsyncChannel`.
///
/// - Parameters:
/// - backpressureStrategy: The backpressure strategy of the ``NIOAsyncChannel`` wrapping the HTTP/2 stream channel.
/// - isOutboundHalfClosureEnabled: If outbound half closure should be enabled for the ``NIOAsyncChannel`` wrapping the HTTP/2 stream channel.
/// - inboundType: The ``NIOAsyncChannel/inboundStream`` message type for the created channel.
/// - backpressureStrategy: The backpressure strategy of the ``NIOAsyncChannel`` wrapping the HTTP/2 stream channel.
/// - isOutboundHalfClosureEnabled: If outbound half closure should be enabled for the ``NIOAsyncChannel`` wrapping the HTTP/2 stream channel.
/// - inboundType: The ``NIOAsyncChannel/inboundStream`` message type for the created channel.
/// This type must match the `InboundOut` type of the final handler added to the stream channel by the `initializer`
/// or ``HTTP2Frame/FramePayload`` if there are none.
/// - outboundType: The ``NIOAsyncChannel/outboundWriter`` message type for the created channel.
/// - outboundType: The ``NIOAsyncChannel/outboundWriter`` message type for the created channel.
/// This type must match the `OutboundIn` type of the final handler added to the stream channel by the `initializer`
/// or ``HTTP2Frame/FramePayload`` if there are none.
/// - initializer: A callback that will be invoked to allow you to configure the
/// - initializer: A callback that will be invoked to allow you to configure the
/// `ChannelPipeline` for the newly created channel.
@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *)
@_spi(AsyncChannel)
Expand Down