Fix several minor typos in comments found in various files (#2455)

Author: gwynne

Sources/NIOCore/ByteBuffer-int.swift

@@ -74,6 +74,7 @@ extension ByteBuffer {
     /// - 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
@@ -91,6 +92,7 @@ extension ByteBuffer {
     ///     - 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

Sources/NIOCore/ChannelHandler.swift

@@ -15,7 +15,7 @@
 /// Base protocol for handlers that handle I/O events or intercept an I/O operation.
 ///
 /// All methods are called from within the `EventLoop` that is assigned to the `Channel` itself.
-//
+///
 /// You should _never_ implement this protocol directly. Please implement one of its sub-protocols.
 public protocol ChannelHandler: AnyObject {
     /// Called when this `ChannelHandler` is added to the `ChannelPipeline`.
@@ -33,7 +33,7 @@ public protocol ChannelHandler: AnyObject {
 
 /// Untyped `ChannelHandler` which handles outbound I/O events or intercept an outbound I/O operation.
 ///
-/// Despite the fact that `write` is one of the methods on this `protocol`, you should avoid assuming that "outbound" events are to do with
+/// Despite the fact that `write` is one of the methods on this protocol, you should avoid assuming that "outbound" events are to do with
 /// writing to channel sources. Instead, "outbound" events are events that are passed *to* the channel source (e.g. a socket): that is, things you tell
 /// the channel source to do. That includes `write` ("write this data to the channel source"), but it also includes `read` ("please begin attempting to read from
 /// the channel source") and `bind` ("please bind the following address"), which have nothing to do with sending data.
@@ -104,7 +104,7 @@ public protocol _ChannelOutboundHandler: ChannelHandler {
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
     func read(context: ChannelHandlerContext)
 
-    /// Called to request that the `Channel` close itself down`.
+    /// Called to request that the `Channel` close itself down.
     ///
     /// 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.
@@ -129,7 +129,7 @@ public protocol _ChannelOutboundHandler: ChannelHandler {
 
 /// Untyped `ChannelHandler` which handles inbound I/O events.
 ///
-/// Despite the fact that `channelRead` is one of the methods on this `protocol`, you should avoid assuming that "inbound" events are to do with
+/// Despite the fact that `channelRead` is one of the methods on this protocol, you should avoid assuming that "inbound" events are to do with
 /// reading from channel sources. Instead, "inbound" events are events that originate *from* the channel source (e.g. the socket): that is, events that the
 /// channel source tells you about. This includes things like `channelRead` ("there is some data to read"), but it also includes things like
 /// `channelWritabilityChanged` ("this source is no longer marked writable").
@@ -161,7 +161,7 @@ public protocol _ChannelInboundHandler: ChannelHandler {
     ///     - 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`.
+    /// 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.
     ///
@@ -215,7 +215,7 @@ public protocol _ChannelInboundHandler: ChannelHandler {
     func errorCaught(context: ChannelHandlerContext, error: Error)
 }
 
-//  Default implementations for the ChannelHandler protocol
+// Default implementations for the ChannelHandler protocol
 extension ChannelHandler {
 
     /// Do nothing by default.
@@ -312,7 +312,7 @@ extension _ChannelInboundHandler {
 /// A `RemovableChannelHandler` is a `ChannelHandler` that can be dynamically removed from a `ChannelPipeline` whilst
 /// the `Channel` is operating normally.
 /// A `RemovableChannelHandler` is required to remove itself from the `ChannelPipeline` (using
-/// `ChannelHandlerContext.removeHandler`) as soon as possible.
+/// `ChannelHandlerContext.leavePipeline`) as soon as possible.
 ///
 /// - 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
@@ -321,23 +321,23 @@ public protocol RemovableChannelHandler: ChannelHandler {
     /// Ask the receiving `RemovableChannelHandler` to remove itself from the `ChannelPipeline` as soon as possible.
     /// The receiving `RemovableChannelHandler` may elect to remove itself sometime after this method call, rather than
     /// immediately, but if it does so it must take the necessary precautions to handle events arriving between the
-    /// invocation of this method and the call to `ChannelHandlerContext.removeHandler` that triggers the actual
+    /// 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
-    ///         remove a `RemovableChannelHandler` from the `ChannelPipeline`, use `ChannelPipeline.remove`.
+    ///         remove a `RemovableChannelHandler` from the `ChannelPipeline`, use `ChannelPipeline.removeHandler`.
     ///
     /// - parameters:
     ///    - context: The `ChannelHandlerContext` of the `RemovableChannelHandler` to be removed from the `ChannelPipeline`.
-    ///    - removalToken: The removal token to hand to `ChannelHandlerContext.removeHandler` to trigger the actual
+    ///    - removalToken: The removal token to hand to `ChannelHandlerContext.leavePipeline` to trigger the actual
     ///                    removal from the `ChannelPipeline`.
     func removeHandler(context: ChannelHandlerContext, removalToken: ChannelHandlerContext.RemovalToken)
 }
 
 extension RemovableChannelHandler {
-    // Implements the default behaviour which is to synchronously remove the handler from the pipeline. Thanks to this,
-    // stateless `ChannelHandler`s can just use `RemovableChannelHandler` as a marker-protocol and declare themselves
-    // as removable without writing any extra code.
+    /// Implements the default behaviour which is to synchronously remove the handler from the pipeline. Thanks to this,
+    /// stateless `ChannelHandler`s can just use `RemovableChannelHandler` as a marker-protocol and declare themselves
+    /// as removable without writing any extra code.
     public func removeHandler(context: ChannelHandlerContext, removalToken: ChannelHandlerContext.RemovalToken) {
         precondition(context.handler === self)
         context.leavePipeline(removalToken: removalToken)

Sources/NIOCore/ChannelOption.swift

@@ -191,7 +191,7 @@ extension ChannelOptions {
             public init() { }
         }
 
-        /// ``DatagramSegmentSize`` controls the 'UDP_SEGMENT' socket option (sometimes reffered to as 'GSO') which allows for
+        /// ``DatagramSegmentSize`` controls the `UDP_SEGMENT` socket option (sometimes reffered to as 'GSO') which allows for
         /// large writes to be sent via `sendmsg` and `sendmmsg` and segmented into separate datagrams by the kernel (or in some cases, the NIC).
         /// The size of segments the large write is split into is controlled by the value of this option (note that writes do not need to be a
         /// multiple of this option).
@@ -204,7 +204,7 @@ extension ChannelOptions {
             public init() { }
         }
 
-        /// ``DatagramReceiveOffload`` sets the 'UDP_GRO' socket option which allows for datagrams to be accumulated
+        /// ``DatagramReceiveOffload`` sets the `UDP_GRO` socket option which allows for datagrams to be accumulated
         /// by the kernel (or in some cases, the NIC) and reduces traversals in the kernel's networking layer.
         ///
         /// This option is currently only supported on Linux (5.10 and newer). Support can be checked

Sources/NIOCore/ChannelPipeline.swift

@@ -109,7 +109,7 @@
 /// - 1 and 2 don't implement `ChannelOutboundHandler`, and therefore the actual evaluation order of a outbound event will be: 5, 4, and 3.
 /// - If 5 implements both `ChannelInboundHandler` and `ChannelOutboundHandler`, the evaluation order of an inbound and a outbound event could be 125 and 543 respectively.
 ///
-/// Note:   Handlers may choose not to propagate messages down the pipeline immediately.  For example a handler may need to wait
+/// - Note: Handlers may choose not to propagate messages down the pipeline immediately.  For example a handler may need to wait
 /// for additional data before sending a protocol event to the next handler in the pipeline.  Due to this you can't assume that later handlers
 /// in the pipeline will receive the same number of events as were sent, or that events of different types will arrive in the same order.
 /// For example - a user event could overtake a data event if a handler is aggregating data events before propagating but immediately

Sources/NIOCore/Codec.swift

@@ -107,7 +107,7 @@ extension ByteToMessageDecoderError {
 ///
 /// ### Implementers Notes
 ///
-/// /// `ByteToMessageHandler` will turn your `ByteToMessageDecoder` into a `ChannelInboundHandler`. `ByteToMessageHandler`
+/// `ByteToMessageHandler` will turn your `ByteToMessageDecoder` into a `ChannelInboundHandler`. `ByteToMessageHandler`
 /// also solves a couple of tricky issues for you. Most importantly, in a `ByteToMessageDecoder` you do _not_ need to
 /// worry about re-entrancy. Your code owns the passed-in `ByteBuffer` for the duration of the `decode`/`decodeLast` call and
 /// can modify it at will.

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() {
@@ -104,7 +104,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 {
@@ -116,7 +116,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() {
@@ -128,7 +128,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 {
@@ -140,7 +140,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() {
@@ -152,7 +152,7 @@ public struct NIOAny {
 
     /// Try unwrapping the wrapped message as `AddressedEnvelope<ByteBuffer>`.
     ///
-    /// returns: The wrapped `AddressedEnvelope<ByteBuffer>` or `nil` if the wrapped message is not an `AddressedEnvelope<ByteBuffer>`.
+    /// - returns: The wrapped `AddressedEnvelope<ByteBuffer>` or `nil` if the wrapped message is not an `AddressedEnvelope<ByteBuffer>`.
     @inlinable
     func tryAsByteEnvelope() -> AddressedEnvelope<ByteBuffer>? {
         if case .bufferEnvelope(let e) = self._storage {
@@ -164,7 +164,7 @@ public struct NIOAny {
 
     /// Force unwrapping the wrapped message as `AddressedEnvelope<ByteBuffer>`.
     ///
-    /// returns: The wrapped `AddressedEnvelope<ByteBuffer>` or crash if the wrapped message is not an `AddressedEnvelope<ByteBuffer>`.
+    /// - returns: The wrapped `AddressedEnvelope<ByteBuffer>` or crash if the wrapped message is not an `AddressedEnvelope<ByteBuffer>`.
     @inlinable
     func forceAsByteEnvelope() -> AddressedEnvelope<ByteBuffer> {
         if let e = tryAsByteEnvelope() {
@@ -176,7 +176,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<T>(type: T.Type = T.self) -> T? {
         switch self._storage {
@@ -191,7 +191,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<T>(type: T.Type = T.self) -> T {
         if let v = tryAsOther(type: type) {
@@ -203,7 +203,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<T>(type: T.Type = T.self) -> T {
         switch T.self {
@@ -222,7 +222,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<T>(type: T.Type = T.self) -> T? {
         switch T.self {
@@ -241,7 +241,7 @@ public struct NIOAny {
 
     /// Unwrap the wrapped message.
     ///
-    /// returns: The wrapped message.
+    /// - returns: The wrapped message.
     @inlinable
     func asAny() -> Any {
         switch self._storage {

Sources/NIOCore/Utilities.swift

@@ -210,24 +210,24 @@ public enum System {
 
 extension System {
     #if os(Linux)
-    /// Returns true if the platform supports 'UDP_SEGMENT' (GSO).
+    /// Returns true if the platform supports `UDP_SEGMENT` (GSO).
     ///
     /// The option can be enabled by setting the ``ChannelOptions/Types/DatagramSegmentSize`` channel option.
     public static let supportsUDPSegmentationOffload: Bool = CNIOLinux_supports_udp_segment()
     #else
-    /// Returns true if the platform supports 'UDP_SEGMENT' (GSO).
+    /// Returns true if the platform supports `UDP_SEGMENT` (GSO).
     ///
     /// The option can be enabled by setting the ``ChannelOptions/Types/DatagramSegmentSize`` channel option.
     public static let supportsUDPSegmentationOffload: Bool = false
     #endif
 
     #if os(Linux)
-    /// Returns true if the platform supports 'UDP_GRO'.
+    /// Returns true if the platform supports `UDP_GRO`.
     ///
     /// The option can be enabled by setting the ``ChannelOptions/Types/DatagramReceiveOffload`` channel option.
     public static let supportsUDPReceiveOffload: Bool = CNIOLinux_supports_udp_gro()
     #else
-    /// Returns true if the platform supports 'UDP_GRO'.
+    /// Returns true if the platform supports `UDP_GRO`.
     ///
     /// The option can be enabled by setting the ``ChannelOptions/Types/DatagramReceiveOffload`` channel option.
     public static let supportsUDPReceiveOffload: Bool = false