network-comments: Added comments, fixed a few typos, and removed conditional parentheses for consistency

Author: agnosticdev

stdlib/public/SDK/Network/NWConnection.swift

@@ -23,6 +23,7 @@ import _SwiftNetworkOverlayShims
 @available(macOS 10.14, iOS 12.0, watchOS 5.0, tvOS 12.0, *)
 public final class NWConnection : CustomDebugStringConvertible {
 
+	/// String based debugging representation of the NWConnection type.
 	public var debugDescription: String {
 		return String("\(self.nw)")
 	}
@@ -354,7 +355,7 @@ public final class NWConnection : CustomDebugStringConvertible {
         }
 
 		/// Create a context for sending, that optionally can set expiration (default 0),
-		/// priority (default 0.5), antecendent (default nil), and protocol metadata (default []]).
+		/// priority (default 0.5), antecedent (default nil), and protocol metadata (default []]).
 		public init(identifier: String, expiration: UInt64 = 0, priority: Double = 0.5, isFinal: Bool = false, antecedent: NWConnection.ContentContext? = nil, metadata: [NWProtocolMetadata]? = []) {
             self.nw = nw_content_context_create(identifier)
 
@@ -478,6 +479,7 @@ public final class NWConnection : CustomDebugStringConvertible {
 		}
 	}
 
+	/// Definition of callbacks used when sending data to the protocol stack. 
 	public enum SendCompletion {
 		/// Completion handler to be invoked when send content has been successfully processed, or failed to send due to an error.
 		/// Note that this does not guarantee that the data was sent out over the network, or acknowledge, but only that

stdlib/public/SDK/Network/NWEndpoint.swift

@@ -79,13 +79,13 @@ private func getaddrinfo_numeric(_ string: String, family: Int32 = 0) -> NWEndpo
 	var result: NWEndpoint.Host? = nil
 
 	if let sa = addrinfo.pointee.ai_addr {
-		if (sa.pointee.sa_family == AF_INET) {
+		if sa.pointee.sa_family == AF_INET {
 			sa.withMemoryRebound(to: sockaddr_in.self, capacity: 1, { (sin) -> Void in
 				result = NWEndpoint.Host.ipv4(IPv4Address(sin.pointee.sin_addr, interface))
 			})
-		} else if (sa.pointee.sa_family == AF_INET6) {
+		} else if sa.pointee.sa_family == AF_INET6 {
 			sa.withMemoryRebound(to: sockaddr_in6.self, capacity: 1, { (sin6) -> Void in
-				if (sin6.pointee.sin6_scope_id != 0) {
+				if sin6.pointee.sin6_scope_id != 0 {
 					interface = NWInterface(Int(sin6.pointee.sin6_scope_id))
 				}
 				let ipv6 = IPv6Address(sin6.pointee.sin6_addr, interface);
@@ -107,14 +107,14 @@ private func getnameinfo_numeric(address: UnsafeRawPointer) -> String {
 	var result : String? = nil
 	let maxLen = socklen_t(100)
 	let storage = UnsafeMutablePointer<Int8>.allocate(capacity: Int(maxLen))
-	if (getnameinfo(sa, socklen_t(sa.pointee.sa_len), storage, maxLen, nil, 0, NI_NUMERICHOST) == 0) {
+	if getnameinfo(sa, socklen_t(sa.pointee.sa_len), storage, maxLen, nil, 0, NI_NUMERICHOST) == 0 {
 		result = String(cString: storage)
 	}
 	storage.deallocate()
 	return result ?? "?"
 }
 
-/// An IP address
+/// An IP address protocol
 @available(macOS 10.14, iOS 12.0, watchOS 5.0, tvOS 12.0, *)
 public protocol IPAddress {
 
@@ -212,7 +212,7 @@ public struct IPv4Address: IPAddress, Hashable, CustomDebugStringConvertible {
 	/// - Parameter interface: An optional network interface to scope the address to. Defaults to nil.
 	/// - Returns: An IPv4Address or nil if the Data parameter did not contain an IPv4 address.
 	public init?(_ rawValue: Data, _ interface: NWInterface? = nil) {
-		if (rawValue.count != MemoryLayout<in_addr>.size) {
+		if rawValue.count != MemoryLayout<in_addr>.size {
 			return nil
 		}
 		let v4 = rawValue.withUnsafeBytes { (ptr: UnsafePointer<in_addr>) -> in_addr in
@@ -244,7 +244,7 @@ public struct IPv4Address: IPAddress, Hashable, CustomDebugStringConvertible {
 	/// The interface the address is scoped to, if any.
 	public let interface: NWInterface?
 
-	// Hashable
+	/// Hashable
 	public static func == (lhs: IPv4Address, rhs: IPv4Address) -> Bool {
 		return lhs.address.s_addr == rhs.address.s_addr && lhs.interface == rhs.interface
 	}
@@ -254,7 +254,7 @@ public struct IPv4Address: IPAddress, Hashable, CustomDebugStringConvertible {
 		hasher.combine(self.interface)
 	}
 
-	// CustomDebugStringConvertible
+	/// CustomDebugStringConvertible returning a debug description string of the IPv4 address and interface or just the address.
 	public var debugDescription: String {
 		var sin = sockaddr_in(self.address, 0)
 		let addressString = getnameinfo_numeric(address: &sin)
@@ -378,7 +378,7 @@ public struct IPv6Address: IPAddress, Hashable, CustomDebugStringConvertible {
 	/// - Parameter interface: An optional interface the address is scoped to. Defaults to nil.
 	/// - Returns: nil unless the raw data contained an IPv6 address
 	public init?(_ rawValue: Data, _ interface: NWInterface? = nil) {
-		if (rawValue.count != MemoryLayout<in6_addr>.size) {
+		if rawValue.count != MemoryLayout<in6_addr>.size {
 			return nil
 		}
 		let v6 = rawValue.withUnsafeBytes { (ptr: UnsafePointer<in6_addr>) -> in6_addr in
@@ -434,7 +434,7 @@ public struct IPv6Address: IPAddress, Hashable, CustomDebugStringConvertible {
 		hasher.combine(self.interface)
 	}
 
-	// CustomDebugStringConvertible
+	/// CustomDebugStringConvertible returning a debug description string of the IPv6 address and interface or just the address.
 	public var debugDescription: String {
 		var sin6 = sockaddr_in6(self.address, 0)
 		let addressString = getnameinfo_numeric(address: &sin6)
@@ -524,7 +524,7 @@ public enum NWEndpoint: Hashable, CustomDebugStringConvertible {
 				return interface
 			}
 		}
-
+		
 		public var debugDescription: String {
 			switch self {
 			case .ipv4(let ip4):
@@ -571,7 +571,7 @@ public enum NWEndpoint: Hashable, CustomDebugStringConvertible {
 			var hints = addrinfo(ai_flags: AI_DEFAULT, ai_family: AF_INET6, ai_socktype: SOCK_STREAM, ai_protocol: 0,
 								 ai_addrlen: 0, ai_canonname: nil, ai_addr: nil, ai_next: nil)
 			var resolved : UnsafeMutablePointer<addrinfo>? = nil
-			if (getaddrinfo(nil, service, &hints, &resolved) != 0) {
+			if getaddrinfo(nil, service, &hints, &resolved) != 0 {
 				return nil
 			}
 
@@ -630,31 +630,32 @@ public enum NWEndpoint: Hashable, CustomDebugStringConvertible {
 		if let nwinterface = nw_endpoint_copy_interface(nw) {
 			interface = NWInterface(nwinterface)
 		}
-		if (nw_endpoint_get_type(nw) == Network.nw_endpoint_type_host)
-		{
+		if nw_endpoint_get_type(nw) == Network.nw_endpoint_type_host{
+
 			let host = NWEndpoint.Host.name(String(cString: nw_endpoint_get_hostname(nw)), interface)
 			self = .hostPort(host: host, port: NWEndpoint.Port(nw_endpoint_get_port(nw)))
-		} else if (nw_endpoint_get_type(nw) == Network.nw_endpoint_type_address) {
+		} else if nw_endpoint_get_type(nw) == Network.nw_endpoint_type_address {
+			
 			let port = NWEndpoint.Port(nw_endpoint_get_port(nw))
 			let address = nw_endpoint_get_address(nw)
-			if (address.pointee.sa_family == AF_INET && address.pointee.sa_len == MemoryLayout<sockaddr_in>.size) {
+			if address.pointee.sa_family == AF_INET && address.pointee.sa_len == MemoryLayout<sockaddr_in>.size {
                 let host = address.withMemoryRebound(to: sockaddr_in.self, capacity: 1) {
                     (sin: UnsafePointer<sockaddr_in>) -> NWEndpoint.Host in
 					return NWEndpoint.Host.ipv4(IPv4Address(sin.pointee.sin_addr, interface))
 				}
 				self = .hostPort(host: host, port: port)
-			} else if (address.pointee.sa_family == AF_INET6 &&
-				address.pointee.sa_len == MemoryLayout<sockaddr_in6>.size) {
+			} else if address.pointee.sa_family == AF_INET6 &&
+				address.pointee.sa_len == MemoryLayout<sockaddr_in6>.size {
 				let host = address.withMemoryRebound(to: sockaddr_in6.self, capacity: 1) {
                     (sin6) -> NWEndpoint.Host in
-					if (interface == nil && sin6.pointee.sin6_scope_id != 0) {
+					if interface == nil && sin6.pointee.sin6_scope_id != 0 {
 						interface = NWInterface(Int(sin6.pointee.sin6_scope_id))
 					}
 					return NWEndpoint.Host.ipv6(IPv6Address(sin6.pointee.sin6_addr,
                                                                                       interface))
 				}
 				self = .hostPort(host: host, port: port)
-			} else if (address.pointee.sa_family == AF_UNIX) {
+			} else if address.pointee.sa_family == AF_UNIX {
 				// sockaddr_un is very difficult to deal with in swift. Fortunately, nw_endpoint_copy_address_string
 				// already does exactly what we need.
 				let path = nw_endpoint_copy_address_string(nw)
@@ -663,7 +664,7 @@ public enum NWEndpoint: Hashable, CustomDebugStringConvertible {
 			} else {
 				return nil
 			}
-		} else if (nw_endpoint_get_type(nw) == Network.nw_endpoint_type_bonjour_service) {
+		} else if nw_endpoint_get_type(nw) == Network.nw_endpoint_type_bonjour_service {
 			self = .service(name: String(cString: nw_endpoint_get_bonjour_service_name(nw)),
 							type: String(cString: nw_endpoint_get_bonjour_service_type(nw)),
 							domain: String(cString: nw_endpoint_get_bonjour_service_domain(nw)),

stdlib/public/SDK/Network/NWParameters.swift

@@ -356,7 +356,7 @@ public final class NWParameters : CustomDebugStringConvertible {
 	/// idempotent data on the connection before the connection may move
 	/// into ready state. As a side effect, this may implicitly enable
 	/// fast open for protocols in the stack, even if they did not have
-	/// fast open expliclty enabled on them (such as the option to enable
+	/// fast open explicitly enabled on them (such as the option to enable
 	/// TCP Fast Open).
 	public var allowFastOpen: Bool {
 		set {

stdlib/public/SDK/Network/NWPath.swift

@@ -22,6 +22,7 @@ public struct NWInterface : Hashable, CustomDebugStringConvertible {
 		return self.name
 	}
 
+	/// Comparison function to determine the equality of two network interfaces by name and kernel index.
 	public static func ==(lhs: NWInterface, rhs: NWInterface) -> Bool {
 		return lhs.index == rhs.index && lhs.name == rhs.name
 	}
@@ -74,7 +75,7 @@ public struct NWInterface : Hashable, CustomDebugStringConvertible {
 			}
 		}
 	}
-
+	// The interface type, such as other, wifi, cellular, wiredEthernet, and loopback.
 	public let type: InterfaceType
 
 	/// The name of the interface, such as "en0"