Skip to content

Commit

Permalink
Tweak formatting of function DocC comments
Browse files Browse the repository at this point in the history 
Motivation:

Tweaking the formatting of the DocC comments enables syntax highlighting
for parameter names in Xcode

Modifications:

Whitespace changes, capitalisation changes and added a parameter
description for `indexing` in HOACKHeaders `replaceOrAdd`, `add`.

Result:

More readable DocC comments
  • Loading branch information
@rnro
rnro committed Jul 5, 2023
1 parent 6e35856 commit 0e61366
Show file tree
Hide file tree
Showing 16 changed files with 342 additions and 337 deletions.
37 changes: 21 additions & 16 deletions Sources/NIOHPACK/HPACKHeader.swift
View file
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
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
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
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
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
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

0 comments on commit 0e61366

Please sign in to comment.