Skip to content

Commit fe02717

Browse files
LukasaLukasa
authored
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
1 parent 27bf96b commit fe02717

23 files changed

+522
-62
lines changed

‎Package.swift‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
// swift-tools-version:5.4
1+
// swift-tools-version:5.6
22
//===----------------------------------------------------------------------===//
33
//
44
// This source file is part of the SwiftNIO open source project
55
//
6-
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
6+
// Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
77
// Licensed under Apache License v2.0
88
//
99
// See LICENSE.txt for license information
@@ -30,6 +30,7 @@ let package = Package(
3030
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
3131
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
3232
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
33+
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
3334
],
3435
targets: [
3536
.target(

‎[email protected]‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// swift-tools-version:5.4
2+
//===----------------------------------------------------------------------===//
3+
//
4+
// This source file is part of the SwiftNIO open source project
5+
//
6+
// Copyright (c) 2017-2018 Apple Inc. and the SwiftNIO project authors
7+
// Licensed under Apache License v2.0
8+
//
9+
// See LICENSE.txt for license information
10+
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
11+
//
12+
// SPDX-License-Identifier: Apache-2.0
13+
//
14+
//===----------------------------------------------------------------------===//
15+
16+
import PackageDescription
17+
18+
let package = Package(
19+
name: "swift-nio-ssh",
20+
platforms: [
21+
.macOS(.v10_15),
22+
.iOS(.v13),
23+
.watchOS(.v6),
24+
.tvOS(.v13),
25+
],
26+
products: [
27+
.library(name: "NIOSSH", targets: ["NIOSSH"]),
28+
],
29+
dependencies: [
30+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
31+
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
32+
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
33+
],
34+
targets: [
35+
.target(
36+
name: "NIOSSH",
37+
dependencies: [
38+
.product(name: "NIOCore", package: "swift-nio"),
39+
.product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
40+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
41+
.product(name: "Crypto", package: "swift-crypto"),
42+
.product(name: "Atomics", package: "swift-atomics"),
43+
]
44+
),
45+
.executableTarget(
46+
name: "NIOSSHClient",
47+
dependencies: [
48+
"NIOSSH",
49+
.product(name: "NIOCore", package: "swift-nio"),
50+
.product(name: "NIOPosix", package: "swift-nio"),
51+
.product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
52+
]
53+
),
54+
.executableTarget(
55+
name: "NIOSSHServer",
56+
dependencies: [
57+
"NIOSSH",
58+
.product(name: "NIOCore", package: "swift-nio"),
59+
.product(name: "NIOPosix", package: "swift-nio"),
60+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
61+
.product(name: "Crypto", package: "swift-crypto"),
62+
]
63+
),
64+
.executableTarget(
65+
name: "NIOSSHPerformanceTester",
66+
dependencies: [
67+
"NIOSSH",
68+
.product(name: "NIOCore", package: "swift-nio"),
69+
.product(name: "NIOEmbedded", package: "swift-nio"),
70+
.product(name: "Crypto", package: "swift-crypto"),
71+
]
72+
),
73+
.testTarget(
74+
name: "NIOSSHTests",
75+
dependencies: [
76+
"NIOSSH",
77+
.product(name: "NIOCore", package: "swift-nio"),
78+
.product(name: "NIOEmbedded", package: "swift-nio"),
79+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
80+
]
81+
),
82+
]
83+
)

‎[email protected]‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
// swift-tools-version:5.5
2+
//===----------------------------------------------------------------------===//
3+
//
4+
// This source file is part of the SwiftNIO open source project
5+
//
6+
// Copyright (c) 2017-2022 Apple Inc. and the SwiftNIO project authors
7+
// Licensed under Apache License v2.0
8+
//
9+
// See LICENSE.txt for license information
10+
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
11+
//
12+
// SPDX-License-Identifier: Apache-2.0
13+
//
14+
//===----------------------------------------------------------------------===//
15+
16+
import PackageDescription
17+
18+
let package = Package(
19+
name: "swift-nio-ssh",
20+
platforms: [
21+
.macOS(.v10_15),
22+
.iOS(.v13),
23+
.watchOS(.v6),
24+
.tvOS(.v13),
25+
],
26+
products: [
27+
.library(name: "NIOSSH", targets: ["NIOSSH"]),
28+
],
29+
dependencies: [
30+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.32.0"),
31+
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),
32+
.package(url: "https://github.com/apple/swift-atomics.git", from: "1.0.2"),
33+
],
34+
targets: [
35+
.target(
36+
name: "NIOSSH",
37+
dependencies: [
38+
.product(name: "NIOCore", package: "swift-nio"),
39+
.product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
40+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
41+
.product(name: "Crypto", package: "swift-crypto"),
42+
.product(name: "Atomics", package: "swift-atomics"),
43+
]
44+
),
45+
.executableTarget(
46+
name: "NIOSSHClient",
47+
dependencies: [
48+
"NIOSSH",
49+
.product(name: "NIOCore", package: "swift-nio"),
50+
.product(name: "NIOPosix", package: "swift-nio"),
51+
.product(name: "NIOConcurrencyHelpers", package: "swift-nio"),
52+
]
53+
),
54+
.executableTarget(
55+
name: "NIOSSHServer",
56+
dependencies: [
57+
"NIOSSH",
58+
.product(name: "NIOCore", package: "swift-nio"),
59+
.product(name: "NIOPosix", package: "swift-nio"),
60+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
61+
.product(name: "Crypto", package: "swift-crypto"),
62+
]
63+
),
64+
.executableTarget(
65+
name: "NIOSSHPerformanceTester",
66+
dependencies: [
67+
"NIOSSH",
68+
.product(name: "NIOCore", package: "swift-nio"),
69+
.product(name: "NIOEmbedded", package: "swift-nio"),
70+
.product(name: "Crypto", package: "swift-crypto"),
71+
]
72+
),
73+
.testTarget(
74+
name: "NIOSSHTests",
75+
dependencies: [
76+
"NIOSSH",
77+
.product(name: "NIOCore", package: "swift-nio"),
78+
.product(name: "NIOEmbedded", package: "swift-nio"),
79+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
80+
]
81+
),
82+
]
83+
)

‎Sources/NIOSSH/Child Channels/ChildChannelOptions.swift‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,46 +18,47 @@ import NIOCore
1818
///
1919
/// Please note that some of NIO's regular `ChannelOptions` are valid on `SSHChildChannel`s.
2020
public struct SSHChildChannelOptions {
21-
/// - seealso: `LocalChannelIdentifierOption`.
21+
/// See: ``SSHChildChannelOptions/Types/LocalChannelIdentifierOption``.
2222
public static let localChannelIdentifier: SSHChildChannelOptions.Types.LocalChannelIdentifierOption = .init()
2323

24-
/// - seealso: `RemoteChannelIdentifierOption`.
24+
/// See: ``SSHChildChannelOptions/Types/RemoteChannelIdentifierOption``.
2525
public static let remoteChannelIdentifier: SSHChildChannelOptions.Types.RemoteChannelIdentifierOption = .init()
2626

27-
/// - seealso: `SSHChannelTypeOption`.
27+
/// See: ``SSHChildChannelOptions/Types/SSHChannelTypeOption``.
2828
public static let sshChannelType: SSHChildChannelOptions.Types.SSHChannelTypeOption = .init()
2929

30-
/// - seealso: `PeerMaximumMessageLengthOption`.
30+
/// See: ``SSHChildChannelOptions/Types/PeerMaximumMessageLengthOption``.
3131
public static let peerMaximumMessageLength: SSHChildChannelOptions.Types.PeerMaximumMessageLengthOption = .init()
3232
}
3333

3434
extension SSHChildChannelOptions {
35+
/// Types for the ``SSHChildChannelOptions``.
3536
public enum Types {}
3637
}
3738

3839
extension SSHChildChannelOptions.Types {
39-
/// `LocalChannelIdentifierOption` allows users to query the channel number assigned locally for a given channel.
40+
/// ``SSHChildChannelOptions/Types/LocalChannelIdentifierOption`` allows users to query the channel number assigned locally for a given channel.
4041
public struct LocalChannelIdentifierOption: ChannelOption, NIOSSHSendable {
4142
public typealias Value = UInt32
4243

4344
public init() {}
4445
}
4546

46-
/// `RemoteChannelIdentifierOption` allows users to query the channel number assigned by the remote peer for a given channel.
47+
/// ``SSHChildChannelOptions/Types/RemoteChannelIdentifierOption`` allows users to query the channel number assigned by the remote peer for a given channel.
4748
public struct RemoteChannelIdentifierOption: ChannelOption, NIOSSHSendable {
4849
public typealias Value = UInt32?
4950

5051
public init() {}
5152
}
5253

53-
/// `SSHChannelTypeOption` allows users to query the type of the channel they're currently using.
54+
/// ``SSHChildChannelOptions/Types/SSHChannelTypeOption`` allows users to query the type of the channel they're currently using.
5455
public struct SSHChannelTypeOption: ChannelOption, NIOSSHSendable {
5556
public typealias Value = SSHChannelType
5657

5758
public init() {}
5859
}
5960

60-
/// `PeerMaximumMessageLengthOption` allows users to query the maximum packet size value reported by the remote peer for a given channel.
61+
/// ``SSHChildChannelOptions/Types/PeerMaximumMessageLengthOption`` allows users to query the maximum packet size value reported by the remote peer for a given channel.
6162
public struct PeerMaximumMessageLengthOption: ChannelOption, NIOSSHSendable {
6263
public typealias Value = UInt32
6364

‎Sources/NIOSSH/Child Channels/ChildChannelUserEvents.swift‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import NIOCore
1616

1717
/// A namespace for SSH channel request events.
1818
public enum SSHChannelRequestEvent {
19+
/// A request for the peer to allocate a pseudo-terminal.
1920
public struct PseudoTerminalRequest: Hashable, NIOSSHSendable {
2021
/// Whether a reply to this PTY request is desired.
2122
public var wantReply: Bool
@@ -91,7 +92,7 @@ public enum SSHChannelRequestEvent {
9192
}
9293
}
9394

94-
/// An EnvironmentRequest communicates a single environment variable the peer wants set.
95+
/// An ``EnvironmentRequest`` communicates a single environment variable the peer wants set.
9596
public struct EnvironmentRequest: Hashable, NIOSSHSendable {
9697
/// The name of the environment variable.
9798
public var name: String
@@ -202,6 +203,9 @@ public enum SSHChannelRequestEvent {
202203
}
203204
}
204205

206+
/// A notification that the user has changed the size of the window.
207+
///
208+
/// Only useful if a pseudo-terminal has been allocated.
205209
public struct WindowChangeRequest: Hashable, NIOSSHSendable {
206210
/// Whether a reply to this window change request is desired.
207211
public var wantReply: Bool {

‎Sources/NIOSSH/Child Channels/SSHChannelData.swift‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,16 @@
1818
import NIOCore
1919
#endif // swift(>=5.6)
2020

21-
/// `SSHChannelData` is the data type that is passed around in `SSHChildChannel` objects.
21+
/// ``SSHChannelData`` is the data type that is passed around in `SSHChildChannel` objects.
2222
///
2323
/// This is the baseline kind of data available for `SSHChildChannel` objects. It encapsulates
2424
/// the difference between `SSH_MSG_CHANNEL_DATA` and `SSH_MSG_CHANNEL_EXTENDED_DATA` by storing
2525
/// them both in a single data type that marks this difference.
2626
public struct SSHChannelData {
27+
/// The type of this data.
2728
public var type: DataType
2829

30+
/// The data in this message.
2931
public var data: IOData
3032

3133
public init(type: DataType, data: IOData) {
@@ -39,8 +41,8 @@ extension SSHChannelData: Equatable {}
3941
extension SSHChannelData: NIOSSHSendable {}
4042

4143
extension SSHChannelData {
42-
/// The type of this channel data. Regular `.channel` data is the standard type of data on an `SSHChannel`,
43-
/// but extended data types (such as `.stderr`) are available as well.
44+
/// The type of this channel data. Regular ``SSHChannelData/DataType/channel`` data is the standard type of data on an `SSHChannel`,
45+
/// but extended data types (such as ``SSHChannelData/DataType/stdErr``) are available as well.
4446
public struct DataType {
4547
internal var _baseType: UInt32
4648

@@ -50,7 +52,7 @@ extension SSHChannelData {
5052
/// Extended data associated with stderr.
5153
public static let stdErr = DataType(_baseType: 1)
5254

53-
/// Construct an `SSHChannelData` for an unknown type of extended data.
55+
/// Construct an ``SSHChannelData`` for an unknown type of extended data.
5456
public init(extended: Int) {
5557
precondition(extended != 0)
5658
self._baseType = UInt32(extended)

‎Sources/NIOSSH/Child Channels/SSHChannelType.swift‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@
1414

1515
import NIOCore
1616

17-
/// `SSHChannelType` represents the type of a single SSH channel.
17+
/// ``SSHChannelType`` represents the type of a single SSH channel.
1818
///
19-
/// SSH Channels are always one of a number of types. The most common type is "session", which
19+
/// SSH Channels are always one of a number of types. The most common type is ``SSHChannelType/session``, which
2020
/// encompasses remote execution of a program, whether that be a single binary, a shell, a subsystem,
2121
/// or something else.
2222
///
@@ -38,6 +38,7 @@ public enum SSHChannelType: Equatable, NIOSSHSendable {
3838
}
3939

4040
extension SSHChannelType {
41+
/// ``SSHChannelType/DirectTCPIP`` is a request from the client to the server to open an outbound connection.
4142
public struct DirectTCPIP: Equatable, NIOSSHSendable {
4243
/// The target host for the forwarded TCP connection.
4344
public var targetHost: String
@@ -72,6 +73,8 @@ extension SSHChannelType {
7273
}
7374

7475
extension SSHChannelType {
76+
/// ``SSHChannelType/ForwardedTCPIP`` is a connection that was accepted from a listening socket on the
77+
/// server and is being forwarded to the client.
7578
public struct ForwardedTCPIP: Equatable, NIOSSHSendable {
7679
/// The host the remote peer connected to. This should be identical to the one that was requested.
7780
public var listeningHost: String

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@ protocol AcceptsUserAuthMessages {
2020

2121
/// This event indicates that server wants us to display the following message to the end user.
2222
public struct NIOUserAuthBannerEvent: Hashable {
23-
/// message to be displayed to end user
23+
/// The message to be displayed to end user
2424
public var message: String
2525

26-
/// tag identifying the language used for `message`, following RFC 3066
26+
/// The tag identifying the language used for `message`, following RFC 3066
2727
public var languageTag: String
2828

2929
public init(message: String, languageTag: String) {
@@ -32,7 +32,7 @@ public struct NIOUserAuthBannerEvent: Hashable {
3232
}
3333
}
3434

35-
/// This event indicates that server accepted our response to authentication challenge. SSH session can be considered active after that.
35+
/// This event indicates that server accepted our response to authentication challenge. The SSH session can be considered active after this point.
3636
public struct UserAuthSuccessEvent: Hashable {
3737
public init() {}
3838
}

0 commit comments

Comments
 (0)