NIOSOCKS docc

Sources/NIOSOCKS/Channel Handlers/SOCKSClientHandler.swift

@@ -19,10 +19,13 @@ import NIOCore
 /// channel's pipeline. Note that SOCKS only supports fully-qualified
 /// domain names and IPv4 or IPv6 sockets, and not UNIX sockets.
 public final class SOCKSClientHandler: ChannelDuplexHandler {
-    
+    /// Accepts `ByteBuffer` as input where receiving.
     public typealias InboundIn = ByteBuffer
+    /// Sends `ByteBuffer` to the next pipeline stage when receiving.
     public typealias InboundOut = ByteBuffer
+    /// Accepts `ByteBuffer` as the type to send.
     public typealias OutboundIn = ByteBuffer
+    /// Sends `ByteBuffer` to the next outbound stage.
     public typealias OutboundOut = ByteBuffer
     
     private let targetAddress: SOCKSAddress
@@ -33,7 +36,7 @@ public final class SOCKSClientHandler: ChannelDuplexHandler {
     
     private var bufferedWrites: MarkedCircularBuffer<(NIOAny, EventLoopPromise<Void>?)> = .init(initialCapacity: 8)
     
-    /// Creates a new `SOCKSClientHandler` that connects to a server
+    /// Creates a new ``SOCKSClientHandler`` that connects to a server
     /// and instructs the server to connect to `targetAddress`.
     /// - parameter targetAddress: The desired end point - note that only IPv4, IPv6, and FQDNs are supported.
     public init(targetAddress: SOCKSAddress) {
@@ -52,7 +55,9 @@ public final class SOCKSClientHandler: ChannelDuplexHandler {
     public func channelActive(context: ChannelHandlerContext) {
         self.beginHandshake(context: context)
     }
-    
+
+    /// Add handler to pipeline and start handshake.
+    /// - Parameter context: Calling context.
     public func handlerAdded(context: ChannelHandlerContext) {
         self.beginHandshake(context: context)
     }

Sources/NIOSOCKS/Channel Handlers/SOCKSServerHandshakeHandler.swift

@@ -17,13 +17,16 @@ import NIOCore
 /// Add this handshake handler to the front of your channel, closest to the network.
 /// The handler will receive bytes from the network and run them through a state machine
 /// and parser to enforce SOCKSv5 protocol correctness. Inbound bytes will by parsed into
-/// `ClientMessage` for downstream consumption. Send `ServerMessage` to this
+/// ``ClientMessage`` for downstream consumption. Send ``ServerMessage`` to this
 /// handler.
 public final class SOCKSServerHandshakeHandler: ChannelDuplexHandler, RemovableChannelHandler {
-    
+    /// Accepts `ByteBuffer` when receiving data.
     public typealias InboundIn = ByteBuffer
+    /// Passes `ClientMessage` to the next stage of the pipeline when receiving data.
     public typealias InboundOut = ClientMessage
+    /// Accepts `ServerMessage` when sending data.
     public typealias OutboundIn = ServerMessage
+    /// Passes `ByteBuffer` to the next pipeline stage when sending data.
     public typealias OutboundOut = ByteBuffer
     
     var inboundBuffer: ByteBuffer?
@@ -52,7 +55,9 @@ public final class SOCKSServerHandshakeHandler: ChannelDuplexHandler, RemovableC
             context.fireErrorCaught(error)
         }
     }
-    
+
+    /// Add hander to pipeline and enter state ready for connection establishment.
+    /// - Parameter context: Calling context
     public func handlerAdded(context: ChannelHandlerContext) {
         do {
             try self.stateMachine.connectionEstablished()
@@ -60,7 +65,9 @@ public final class SOCKSServerHandshakeHandler: ChannelDuplexHandler, RemovableC
             context.fireErrorCaught(error)
         }
     }
-    
+
+    /// Remove handler from channel pipeline.  Causes any inbound buffer to be surfaced.
+    /// - Parameter context:  Calling context.
     public func handlerRemoved(context: ChannelHandlerContext) {
         guard let buffer = self.inboundBuffer else {
             return

Sources/NIOSOCKS/Messages/ClientGreeting.swift

@@ -26,7 +26,7 @@ public struct ClientGreeting: Hashable {
     /// The SOCKS server will select one to use.
     public var methods: [AuthenticationMethod]
     
-    /// Creates a new `ClientGreeting`
+    /// Creates a new ``ClientGreeting``
     /// - parameter methods: The client-supported authentication methods.
     public init(methods: [AuthenticationMethod]) {
         self.methods = methods

Sources/NIOSOCKS/Messages/SOCKSRequest.swift

@@ -35,7 +35,7 @@ public struct SOCKSRequest: Hashable {
     /// The target host address.
     public var addressType: SOCKSAddress
     
-    /// Creates a new `SOCKSRequest`.
+    /// Creates a new ``SOCKSRequest``.
     /// - parameter command: How to connect to the host.
     /// - parameter addressType: The target host address.
     public init(command: SOCKSCommand, addressType: SOCKSAddress) {
@@ -87,9 +87,10 @@ public struct SOCKSCommand: Hashable {
     /// Used to establish an association within the UDP relay process to
     /// handle UDP datagrams.
     public static let udpAssociate = SOCKSCommand(value: 0x03)
-    
+
+    /// Command value as defined in RFC
     public var value: UInt8
-    
+
     public init(value: UInt8) {
         self.value = value
     }
@@ -99,9 +100,9 @@ public struct SOCKSCommand: Hashable {
 
 /// The address used to connect to the target host.
 public enum SOCKSAddress: Hashable {
-    
+    /// Socket Adress
     case address(SocketAddress)
-    
+    /// Host and port
     case domain(String, port: Int)
     
     static let ipv4IdentifierByte: UInt8 = 0x01

Sources/NIOSOCKS/Messages/SOCKSResponse.swift

@@ -30,7 +30,7 @@ public struct SOCKSResponse: Hashable {
     /// The host address.
     public var boundAddress: SOCKSAddress
     
-    /// Creates a new `SOCKSResponse`.
+    /// Creates a new ``SOCKSResponse``.
     /// - parameter reply: The status of the connection - used to check if the request
     /// succeeded or failed.
     /// - parameter boundAddress: The host address.

Sources/NIOSOCKS/Messages/SelectedAuthenticationMethod.swift

@@ -25,7 +25,7 @@ public struct SelectedAuthenticationMethod: Hashable {
     /// The server's selected authentication method.
     public var method: AuthenticationMethod
     
-    /// Creates a new `MethodSelection` wrapping an `AuthenticationMethod`.
+    /// Creates a new `MethodSelection` wrapping an ``AuthenticationMethod``.
     /// - parameter method: The selected `AuthenticationMethod`.
     public init(method: AuthenticationMethod) {
         self.method = method