Fix documentation and add support for CI-ing it (#196)

* Fix documentation and add support for CI-ing it

* Soundness cleanup

Sources/NIOExtras/DebugInboundEventsHandler.swift

@@ -57,7 +57,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         self.logger = logger
     }
 
-    /// Logs ``Event.registered`` to ``logger``
+    /// Logs ``Event/registered`` to `logger`
     /// Called when the `Channel` has successfully registered with its `EventLoop` to handle I/O.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -66,7 +66,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelRegistered()
     }
 
-    /// Logs ``Event.unregistered`` to ``logger``
+    /// Logs ``Event/unregistered`` to `logger`
     /// Called when the `Channel` has unregistered from its `EventLoop`, and so will no longer be receiving I/O events.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -75,7 +75,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelUnregistered()
     }
 
-    /// Logs ``Event.active`` to ``logger``
+    /// Logs ``Event/active`` to `logger`
     /// Called when the `Channel` has become active, and is able to send and receive data.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -84,7 +84,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelActive()
     }
 
-    /// Logs ``Event.inactive`` to ``logger``
+    /// Logs ``Event/inactive`` to `logger`
     /// Called when the `Channel` has become inactive and is no longer able to send and receive data`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -93,7 +93,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelInactive()
     }
 
-    /// Logs ``Event.read`` to ``logger``
+    /// Logs ``Event/read(data:)`` to `logger`
     /// Called when some data has been read from the remote peer.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -103,7 +103,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelRead(data)
     }
 
-    /// Logs ``Event.readComplete`` to ``logger``
+    /// Logs ``Event/readComplete`` to `logger`
     /// 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.
@@ -114,7 +114,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelReadComplete()
     }
 
-    /// Logs ``Event.writabilityChanged`` to ``logger``
+    /// Logs ``Event/writabilityChanged(isWritable:)`` to `logger`
     /// 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.
     /// - parameters:
@@ -124,7 +124,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireChannelWritabilityChanged()
     }
 
-    /// Logs ``Event.userInboundEventTriggered`` to ``logger``
+    /// Logs ``Event/userInboundEventTriggered(event:)`` to `logger`
     /// Called when a user inbound event has been triggered.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -134,7 +134,7 @@ public class DebugInboundEventsHandler: ChannelInboundHandler {
         context.fireUserInboundEventTriggered(event)
     }
 
-    /// Logs ``Event.errorCaught`` to ``logger``
+    /// Logs ``Event/errorCaught(_:)`` to `logger`
     /// An error was encountered earlier in the inbound `ChannelPipeline`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.

Sources/NIOExtras/DebugOutboundEventsHandler.swift

@@ -57,7 +57,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         self.logger = logger
     }
 
-    /// Logs ``Event.register`` to ``logger``
+    /// Logs ``Event/register`` to `logger`
     /// Called to request that the `Channel` register itself for I/O events with its `EventLoop`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -67,7 +67,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.register(promise: promise)
     }
 
-    /// Logs ``Event.bind`` to ``logger``
+    /// Logs ``Event/bind(address:)`` to `logger`
     /// Called to request that the `Channel` bind to a specific `SocketAddress`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -78,7 +78,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.bind(to: address, promise: promise)
     }
 
-    /// Logs ``Event.connect`` to ``logger``
+    /// Logs ``Event/connect(address:)`` to `logger`
     /// Called to request that the `Channel` connect to a given `SocketAddress`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -89,7 +89,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.connect(to: address, promise: promise)
     }
 
-    /// Logs ``Event.data`` to ``logger``
+    /// Logs ``Event/write(data:)`` to `logger`
     /// Called to request a write operation.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -100,7 +100,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.write(data, promise: promise)
     }
 
-    /// Logs ``Event.flush`` to ``logger``
+    /// Logs ``Event/flush`` to `logger`
     /// Called to request that the `Channel` flush all pending writes. The flush operation will try to flush out all previous written messages
     /// that are pending.
     /// - parameters:
@@ -110,7 +110,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.flush()
     }
 
-    /// Logs ``Event.read`` to ``logger``
+    /// Logs ``Event/read`` to `logger`
     /// 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.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -119,7 +119,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.read()
     }
 
-    /// Logs ``Event.close`` to ``logger``
+    /// Logs ``Event/close(mode:)`` to `logger`
     /// Called to request that the `Channel` close itself down`.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.
@@ -130,7 +130,7 @@ public class DebugOutboundEventsHandler: ChannelOutboundHandler {
         context.close(mode: mode, promise: promise)
     }
 
-    /// Logs ``Event.triggerUserOutboundEvent`` to ``logger``
+    /// Logs ``Event/triggerUserOutboundEvent(event:)`` to `logger`
     /// Called when an user outbound event is triggered.
     /// - parameters:
     ///     - context: The `ChannelHandlerContext` which this `ChannelHandler` belongs to.

Sources/NIOExtras/HTTP1ProxyConnectHandler.swift

@@ -260,7 +260,7 @@ public final class NIOHTTP1ProxyConnectHandler: ChannelDuplexHandler, RemovableC
         }
     }
 
-    /// Error types for ``HTTP1ProxyConnectHandler``
+    /// Error types for ``NIOHTTP1ProxyConnectHandler``
     public struct Error: Swift.Error {
         fileprivate enum Details {
             case proxyAuthenticationRequired

Tests/NIOExtrasTests/RequestResponseWithIDHandlerTest+XCTest.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftNIO open source project
 //
-// Copyright (c) 2018-2022 Apple Inc. and the SwiftNIO project authors
+// Copyright (c) 2018-2023 Apple Inc. and the SwiftNIO project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information

docker/docker-compose.2004.55.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.5"
 
+  documentation-check:
+    image: swift-nio-extras:20.04-5.5
+
   test:
     image: swift-nio-extras:20.04-5.5
 

docker/docker-compose.2004.56.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.6"
 
+  documentation-check:
+    image: swift-nio-extras:20.04-5.6
+
   test:
     image: swift-nio-extras:20.04-5.6
 

docker/docker-compose.2204.57.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "jammy"
         swift_version: "5.7"
 
+  documentation-check:
+    image: swift-nio-extras:22.04-5.7
+
   test:
     image: swift-nio-extras:22.04-5.7
 

docker/docker-compose.2204.58.yaml

@@ -13,5 +13,8 @@ services:
     environment:
       - IMPORT_CHECK_ARG=--explicit-target-dependency-import-check error
 
+  documentation-check:
+    image: swift-nio-extras:22.04-5.8
+
   shell:
     image: swift-nio-extras:22.04-5.8

docker/docker-compose.2204.main.yaml

@@ -13,5 +13,8 @@ services:
     environment:
       - IMPORT_CHECK_ARG=--explicit-target-dependency-import-check error
 
+  documentation-check:
+    image: swift-nio-extras:22.04-main
+
   shell:
     image: swift-nio-extras:22.04-main

docker/docker-compose.yaml

@@ -26,6 +26,10 @@ services:
     <<: *common
     command: /bin/bash -xcl "./scripts/soundness.sh"
 
+  documentation-check:
+    <<: *common
+    command: /bin/bash -xcl "./scripts/check-docs.sh"
+
   test:
     <<: *common
     command: /bin/bash -xcl "cat /etc/lsb-release && swift -version && swift test -Xswiftc -warnings-as-errors --enable-test-discovery $${SANITIZER_ARG-} $${IMPORT_CHECK_ARG-}"

scripts/check-docs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the SwiftNIO open source project
+##
+## Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+set -eu
+
+raw_targets=$(sed -E -n -e 's/^.* - documentation_targets: \[(.*)\].*$/\1/p' .spi.yml)
+targets=(${raw_targets//,/ })
+
+for target in "${targets[@]}"; do
+  swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze --level detailed
+done