Use Docc for documentation (#118)

Motivation

Documentation is nice, and we can help support users by providing useful
clear docs.

Modifications

Add Docc to 5.6 and later builds
Make sure symbol references work
Add overview docs

Result

Nice rendering docs

Package.swift

@@ -1,9 +1,9 @@
-// swift-tools-version:5.4
+// swift-tools-version:5.6
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftNIO open source project
 //
-// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
+// Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -30,6 +30,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
         .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
         .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
     ],
     targets: [
         .target(

Package@swift-5.4.swift

@@ -0,0 +1,83 @@
+// swift-tools-version:5.4
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2017-2018 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
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-nio-ssh",
+    platforms: [
+        .macOS(.v10_15),
+        .iOS(.v13),
+        .watchOS(.v6),
+        .tvOS(.v13),
+    ],
+    products: [
+        .library(name: "NIOSSH", targets: ["NIOSSH"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
+        .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+    ],
+    targets: [
+        .target(
+            name: "NIOSSH",
+            dependencies: [
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHClient",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHServer",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHPerformanceTester",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+            ]
+        ),
+        .testTarget(
+            name: "NIOSSHTests",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+            ]
+        ),
+    ]
+)

Package@swift-5.5.swift

@@ -0,0 +1,83 @@
+// swift-tools-version:5.5
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftNIO open source project
+//
+// Copyright (c) 2017-2022 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
+//
+//===----------------------------------------------------------------------===//
+
+import PackageDescription
+
+let package = Package(
+    name: "swift-nio-ssh",
+    platforms: [
+        .macOS(.v10_15),
+        .iOS(.v13),
+        .watchOS(.v6),
+        .tvOS(.v13),
+    ],
+    products: [
+        .library(name: "NIOSSH", targets: ["NIOSSH"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
+        .package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
+        .package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
+    ],
+    targets: [
+        .target(
+            name: "NIOSSH",
+            dependencies: [
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+                .product(name: "Atomics", package: "swift-atomics"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHClient",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHServer",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOPosix", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+            ]
+        ),
+        .executableTarget(
+            name: "NIOSSHPerformanceTester",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "Crypto", package: "swift-crypto"),
+            ]
+        ),
+        .testTarget(
+            name: "NIOSSHTests",
+            dependencies: [
+                "NIOSSH",
+                .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOEmbedded", package: "swift-nio"),
+                .product(name: "NIOFoundationCompat", package: "swift-nio"),
+            ]
+        ),
+    ]
+)

Sources/NIOSSH/Child Channels/ChildChannelOptions.swift

@@ -18,46 +18,47 @@ import NIOCore
 ///
 /// Please note that some of NIO's regular `ChannelOptions` are valid on `SSHChildChannel`s.
 public struct SSHChildChannelOptions {
-    /// - seealso: `LocalChannelIdentifierOption`.
+    /// See: ``SSHChildChannelOptions/Types/LocalChannelIdentifierOption``.
     public static let localChannelIdentifier: SSHChildChannelOptions.Types.LocalChannelIdentifierOption = .init()
 
-    /// - seealso: `RemoteChannelIdentifierOption`.
+    /// See: ``SSHChildChannelOptions/Types/RemoteChannelIdentifierOption``.
     public static let remoteChannelIdentifier: SSHChildChannelOptions.Types.RemoteChannelIdentifierOption = .init()
 
-    /// - seealso: `SSHChannelTypeOption`.
+    /// See: ``SSHChildChannelOptions/Types/SSHChannelTypeOption``.
     public static let sshChannelType: SSHChildChannelOptions.Types.SSHChannelTypeOption = .init()
 
-    /// - seealso: `PeerMaximumMessageLengthOption`.
+    /// See: ``SSHChildChannelOptions/Types/PeerMaximumMessageLengthOption``.
     public static let peerMaximumMessageLength: SSHChildChannelOptions.Types.PeerMaximumMessageLengthOption = .init()
 }
 
 extension SSHChildChannelOptions {
+    /// Types for the ``SSHChildChannelOptions``.
     public enum Types {}
 }
 
 extension SSHChildChannelOptions.Types {
-    /// `LocalChannelIdentifierOption` allows users to query the channel number assigned locally for a given channel.
+    /// ``SSHChildChannelOptions/Types/LocalChannelIdentifierOption`` allows users to query the channel number assigned locally for a given channel.
     public struct LocalChannelIdentifierOption: ChannelOption, NIOSSHSendable {
         public typealias Value = UInt32
 
         public init() {}
     }
 
-    /// `RemoteChannelIdentifierOption` allows users to query the channel number assigned by the remote peer for a given channel.
+    /// ``SSHChildChannelOptions/Types/RemoteChannelIdentifierOption`` allows users to query the channel number assigned by the remote peer for a given channel.
     public struct RemoteChannelIdentifierOption: ChannelOption, NIOSSHSendable {
         public typealias Value = UInt32?
 
         public init() {}
     }
 
-    /// `SSHChannelTypeOption` allows users to query the type of the channel they're currently using.
+    /// ``SSHChildChannelOptions/Types/SSHChannelTypeOption`` allows users to query the type of the channel they're currently using.
     public struct SSHChannelTypeOption: ChannelOption, NIOSSHSendable {
         public typealias Value = SSHChannelType
 
         public init() {}
     }
 
-    /// `PeerMaximumMessageLengthOption` allows users to query the maximum packet size value reported by the remote peer for a given channel.
+    /// ``SSHChildChannelOptions/Types/PeerMaximumMessageLengthOption`` allows users to query the maximum packet size value reported by the remote peer for a given channel.
     public struct PeerMaximumMessageLengthOption: ChannelOption, NIOSSHSendable {
         public typealias Value = UInt32
 

Sources/NIOSSH/Child Channels/ChildChannelUserEvents.swift

@@ -16,6 +16,7 @@ import NIOCore
 
 /// A namespace for SSH channel request events.
 public enum SSHChannelRequestEvent {
+    /// A request for the peer to allocate a pseudo-terminal.
     public struct PseudoTerminalRequest: Hashable, NIOSSHSendable {
         /// Whether a reply to this PTY request is desired.
         public var wantReply: Bool
@@ -91,7 +92,7 @@ public enum SSHChannelRequestEvent {
         }
     }
 
-    /// An EnvironmentRequest communicates a single environment variable the peer wants set.
+    /// An ``EnvironmentRequest`` communicates a single environment variable the peer wants set.
     public struct EnvironmentRequest: Hashable, NIOSSHSendable {
         /// The name of the environment variable.
         public var name: String
@@ -202,6 +203,9 @@ public enum SSHChannelRequestEvent {
         }
     }
 
+    /// A notification that the user has changed the size of the window.
+    ///
+    /// Only useful if a pseudo-terminal has been allocated.
     public struct WindowChangeRequest: Hashable, NIOSSHSendable {
         /// Whether a reply to this window change request is desired.
         public var wantReply: Bool {

Sources/NIOSSH/Child Channels/SSHChannelData.swift

@@ -18,14 +18,16 @@
 import NIOCore
 #endif // swift(>=5.6)
 
-/// `SSHChannelData` is the data type that is passed around in `SSHChildChannel` objects.
+/// ``SSHChannelData`` is the data type that is passed around in `SSHChildChannel` objects.
 ///
 /// This is the baseline kind of data available for `SSHChildChannel` objects. It encapsulates
 /// the difference between `SSH_MSG_CHANNEL_DATA` and `SSH_MSG_CHANNEL_EXTENDED_DATA` by storing
 /// them both in a single data type that marks this difference.
 public struct SSHChannelData {
+    /// The type of this data.
     public var type: DataType
 
+    /// The data in this message.
     public var data: IOData
 
     public init(type: DataType, data: IOData) {
@@ -39,8 +41,8 @@ extension SSHChannelData: Equatable {}
 extension SSHChannelData: NIOSSHSendable {}
 
 extension SSHChannelData {
-    /// The type of this channel data. Regular `.channel` data is the standard type of data on an `SSHChannel`,
-    /// but extended data types (such as `.stderr`) are available as well.
+    /// The type of this channel data. Regular ``SSHChannelData/DataType/channel`` data is the standard type of data on an `SSHChannel`,
+    /// but extended data types (such as ``SSHChannelData/DataType/stdErr``) are available as well.
     public struct DataType {
         internal var _baseType: UInt32
 
@@ -50,7 +52,7 @@ extension SSHChannelData {
         /// Extended data associated with stderr.
         public static let stdErr = DataType(_baseType: 1)
 
-        /// Construct an `SSHChannelData` for an unknown type of extended data.
+        /// Construct an ``SSHChannelData`` for an unknown type of extended data.
         public init(extended: Int) {
             precondition(extended != 0)
             self._baseType = UInt32(extended)

Sources/NIOSSH/Child Channels/SSHChannelType.swift

@@ -14,9 +14,9 @@
 
 import NIOCore
 
-/// `SSHChannelType` represents the type of a single SSH channel.
+/// ``SSHChannelType`` represents the type of a single SSH channel.
 ///
-/// SSH Channels are always one of a number of types. The most common type is "session", which
+/// SSH Channels are always one of a number of types. The most common type is ``SSHChannelType/session``, which
 /// encompasses remote execution of a program, whether that be a single binary, a shell, a subsystem,
 /// or something else.
 ///
@@ -38,6 +38,7 @@ public enum SSHChannelType: Equatable, NIOSSHSendable {
 }
 
 extension SSHChannelType {
+    /// ``SSHChannelType/DirectTCPIP`` is a request from the client to the server to open an outbound connection.
     public struct DirectTCPIP: Equatable, NIOSSHSendable {
         /// The target host for the forwarded TCP connection.
         public var targetHost: String
@@ -72,6 +73,8 @@ extension SSHChannelType {
 }
 
 extension SSHChannelType {
+    /// ``SSHChannelType/ForwardedTCPIP`` is a connection that was accepted from a listening socket on the
+    /// server and is being forwarded to the client.
     public struct ForwardedTCPIP: Equatable, NIOSSHSendable {
         /// The host the remote peer connected to. This should be identical to the one that was requested.
         public var listeningHost: String

Sources/NIOSSH/Connection State Machine/Operations/AcceptsUserAuthMessages.swift

@@ -20,10 +20,10 @@ protocol AcceptsUserAuthMessages {
 
 /// This event indicates that server wants us to display the following message to the end user.
 public struct NIOUserAuthBannerEvent: Hashable {
-    /// message to be displayed to end user
+    /// The message to be displayed to end user
     public var message: String
 
-    /// tag  identifying the language used for `message`, following RFC 3066
+    /// The tag  identifying the language used for `message`, following RFC 3066
     public var languageTag: String
 
     public init(message: String, languageTag: String) {
@@ -32,7 +32,7 @@ public struct NIOUserAuthBannerEvent: Hashable {
     }
 }
 
-/// This event indicates that server accepted our response to authentication challenge. SSH session can be considered active after that.
+/// This event indicates that server accepted our response to authentication challenge. The SSH session can be considered active after this point.
 public struct UserAuthSuccessEvent: Hashable {
     public init() {}
 }