docs clean up and fix up - spelling, grammar, and style guide alignment

Sources/SwiftNetwork/Context/NetworkContext.swift

@@ -62,21 +62,25 @@ public final class NetworkContext: NetworkContextProtocol, @unchecked Sendable {
     }
 
     public protocol Scheduler: AnyObject {
-        /// Run an immediate task.  No assumptions are made about how the task will be run.
+        /// Runs an immediate task. No assumptions are made about how the task is run.
         func runImmediate(_ task: @escaping (() -> Void))
-        /// Schedule a task to be run after a delay of the given `milliseconds`, using a reference.
+        /// Schedules a task to run after a delay, using a reference.
+        ///
+        /// The `milliseconds` parameter specifies the delay before the task runs.
         func schedule(_ task: @escaping (() -> Void), milliseconds: Int64, reference: TimerReference)
-        /// Unschedule a task with a handle
+        /// Unschedules a task with a reference.
         func unschedule(reference: TimerReference)
-        /// Whether the current code is running in the scheduler
+        /// A Boolean value that indicates whether the current code is running in the scheduler.
         var runningInScheduler: Bool { get }
     }
 
-    /// Indicate the privacy level for the context. Public is good for contexts that will be used only with
-    /// endpoints that do not divulge information about what the user is doing such as a process that always connects
-    /// to the same server. Private will hide the endpoints involved in connections. This level is appropriate for a
-    /// browser, where hostnames would indicate a great deal of information about what a user is doing. Sensitive will
-    /// suppress all logging and is appropriate for something like private browsing.
+    /// Indicates the privacy level for the context.
+    ///
+    /// `publicLogs` is good for contexts used only with endpoints that don't divulge information
+    /// about what the app is doing, such as a process that always connects to the same server.
+    /// `privateLogs` hides the endpoints involved in connections; this level is appropriate for a
+    /// browser, where hostnames would indicate a great deal of information about what the app is doing.
+    /// `sensitiveLogs` suppresses all logging and is appropriate for something like private browsing.
     enum PrivacyLevel: Hashable, CustomStringConvertible {
         case publicLogs
         case privateLogs
@@ -340,20 +344,22 @@ extension NetworkContext {
         init(globals: Globals) {
             self.globals = globals
         }
-        /// Run an immediate task.  No assumptions are made about how the task will be run.
+        /// Runs an immediate task. No assumptions are made about how the task is run.
         func runImmediate(_ task: @escaping (() -> Void)) {
             globals.queue.async(execute: DispatchWorkItem(block: task))
         }
-        /// Schedule a task to be run after a delay of the given `milliseconds`, using a reference.
+        /// Schedules a task to run after a delay, using a reference.
+        ///
+        /// The `milliseconds` parameter specifies the delay before the task runs.
         func schedule(_ task: @escaping (() -> Void), milliseconds: Int64, reference: TimerReference) {
             let targetTime = DispatchTime.now() + DispatchTimeInterval.milliseconds(Int(milliseconds))
             globals.timerList.insert(targetTime: targetTime, reference: reference, task: task)
         }
-        /// Unschedule a task with a reference
+        /// Unschedules a task with a reference.
         func unschedule(reference: TimerReference) {
             globals.timerList.remove(for: reference)
         }
-        /// Whether the current code is running in the scheduler
+        /// A Boolean value that indicates whether the current code is running in the scheduler.
         var runningInScheduler: Bool {
             // TODO: Not supported by DispatchQueue
             fatalError("Unsupported")

Sources/SwiftNetwork/Endpoint/EthernetAddress.swift

@@ -36,7 +36,7 @@ public struct EthernetAddress: Hashable, CustomDebugStringConvertible {
         }
     }
 
-    /// An IPv6 address as a byte array
+    /// An Ethernet address as a byte array.
     public init?(_ bytes: [UInt8]) {
         guard bytes.count == MemoryLayout<EthernetAddressStorage>.size else {
             return nil

Sources/SwiftNetwork/Endpoint/IPAddress.swift

@@ -12,18 +12,18 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// IPAddress is just a stub for now.
+/// A stub protocol that represents an IP address.
 protocol IPAddress: Sendable {
 
-    /// Create IPAddress from raw bytes
+    /// Creates an IP address from raw bytes.
     init?(_ bytes: [UInt8])
 
-    /// Indicates the address family used for the IPAddress type
+    /// The address family used by this IP address.
     var addressFamily: AddressFamily { get }
 
-    /// Indicates if this address is loopback
+    /// A Boolean value that indicates whether this address is a loopback address.
     var isLoopback: Bool { get }
 
-    /// Indicates if this address is multicast
+    /// A Boolean value that indicates whether this address is a multicast address.
     var isMulticast: Bool { get }
 }

Sources/SwiftNetwork/Endpoint/IPv4Address.swift

@@ -14,27 +14,27 @@
 
 public struct IPv4Address: IPAddress, Hashable, CustomDebugStringConvertible {
 
-    /// The IPv4 any address used for listening
+    /// The IPv4 "any" address used for listening.
     public static var any: IPv4Address {
         IPv4Address(UInt32(0x0000_0000).bigEndian)
     }
 
-    /// The IPv4 broadcast address used to broadcast to all hosts
+    /// The IPv4 broadcast address used to broadcast to all hosts.
     public static var broadcast: IPv4Address {
         IPv4Address(UInt32(0xffff_ffff).bigEndian)
     }
 
-    /// The IPv4 loopback address
+    /// The IPv4 loopback address.
     public static var loopback: IPv4Address {
         IPv4Address(UInt32(0x7f00_0001).bigEndian)
     }
 
-    /// Indicates if this IPv4 address is loopback (127.0.0.1)
+    /// A Boolean value that indicates whether this IPv4 address is the loopback address (127.0.0.1).
     public var isLoopback: Bool {
         self == IPv4Address.loopback
     }
 
-    /// Indicates if this IPv4 address is multicast
+    /// A Boolean value that indicates whether this IPv4 address is a multicast address.
     public var isMulticast: Bool {
         let v4WireAddress = self.address
         let mask = (0xF000_0000 as UInt32).bigEndian
@@ -78,7 +78,7 @@ public struct IPv4Address: IPAddress, Hashable, CustomDebugStringConvertible {
         self.address = rawValue
     }
 
-    /// An IPv4 address as a byte array
+    /// An IPv4 address as a byte array.
     public init?(_ bytes: [UInt8]) {
         guard bytes.count == MemoryLayout<UInt32>.size else {
             return nil

Sources/SwiftNetwork/Endpoint/IPv6Address.swift

@@ -14,22 +14,24 @@
 
 public struct IPv6Address: IPAddress, Hashable, CustomDebugStringConvertible {
 
-    /// IPv6 any address
+    /// The IPv6 "any" address.
     public static var any: IPv6Address {
         IPv6Address((0, 0, 0, 0))
     }
 
-    /// IPv6 broadcast address
+    /// The IPv6 broadcast address.
     public static var broadcast: IPv6Address {
         IPv6Address((0, 0, 0, 0))
     }
 
-    /// IPv6 loopback address
+    /// The IPv6 loopback address.
     public static var loopback: IPv6Address {
         IPv6Address((0, 0, 0, UInt32(1).bigEndian))
     }
 
-    /// Is the loopback address "::1"
+    /// A Boolean value that indicates whether this is the loopback address.
+    ///
+    /// The IPv6 loopback address is `::1`.
     public var isLoopback: Bool {
         (self == IPv6Address.loopback)
     }
@@ -78,18 +80,22 @@ public struct IPv6Address: IPAddress, Hashable, CustomDebugStringConvertible {
         return withUnsafeBytes(of: &addressFirstChunk) { $0[1] & 0xf0 }
     }
 
-    /// Is multicast
+    /// A Boolean value that indicates whether this is a multicast address.
     var isMulticast: Bool {
         var addressFirstChunk = self.address.0
         return withUnsafeBytes(of: &addressFirstChunk) { $0[0] == 0xff }
     }
 
-    /// Is an IPv4 mapped address such as "::ffff:1.2.3.4"
+    /// A Boolean value that indicates whether this is an IPv4-mapped address.
+    ///
+    /// For example, `::ffff:1.2.3.4`.
     var isIPv4Mapped: Bool {
         Self.isIPv4Mapped(from: address)
     }
 
-    /// For IPv6 addresses that are IPv4 mapped, returns the IPv4 address
+    /// The IPv4 address for an IPv4-mapped IPv6 address.
+    ///
+    /// Returns `nil` if this address isn't IPv4-mapped.
     var asIPv4: IPv4Address? {
         guard self.isIPv4Mapped else {
             return nil
@@ -108,7 +114,7 @@ public struct IPv6Address: IPAddress, Hashable, CustomDebugStringConvertible {
         self.address = tuple
     }
 
-    /// An IPv6 address as a byte array
+    /// An IPv6 address as a byte array.
     public init?(_ bytes: [UInt8]) {
         guard bytes.count == MemoryLayout<UInt32>.size * 4 else {
             return nil

Sources/SwiftNetwork/Endpoint/NetlinkAddress.swift

@@ -23,16 +23,16 @@ internal import os
 // NetlinkAddress represents sockaddr_nl on Linux
 struct NetlinkAddress: IPAddress, Hashable, CustomDebugStringConvertible {
 
-    /// Indicates if this address is loopback
+    /// A Boolean value that indicates whether this address is a loopback address.
     var isLoopback: Bool { false }
 
-    /// Indicates if this address is multicast
+    /// A Boolean value that indicates whether this address is a multicast address.
     var isMulticast: Bool {
         // TODO: Extend using nl_groups
         false
     }
 
-    /// Create IPAddress from raw bytes
+    /// Creates a Netlink address from raw bytes.
     init?(_ bytes: [UInt8]) {
         if bytes.count >= NetlinkAddress.layoutSize {
             #if os(Linux)

Sources/SwiftNetwork/EndpointFlow/EndpointFlow.swift

@@ -30,21 +30,21 @@ internal import Synchronization
 
 final class EndpointFlow: CustomDebugStringConvertible {
 
-    /// Datapath logging
+    /// State used to emit logs on the data path.
     public var log = NetworkLoggerState()
 
     enum State: Equatable, Sendable {
-        /// The initial state prior to start
+        /// The initial state prior to start.
         case setup
-        /// Waiting connections have not yet been started, or do not have a viable network
+        /// Waiting connections haven't yet been started, or don't have a viable network.
         case waiting(NetworkError)
-        /// Preparing connections are actively establishing the connection
+        /// Preparing connections are actively establishing the connection.
         case preparing
-        /// Ready connections can send and receive data
+        /// Ready connections can send and receive data.
         case ready
-        /// Failed connections are disconnected and can no longer send or receive data
+        /// Failed connections are disconnected and can no longer send or receive data.
         case failed(NetworkError)
-        /// Cancelled connections have been invalidated by the client and will send no more events
+        /// Cancelled connections have been invalidated by the client and send no more events.
         case cancelled
 
         public static func == (lhs: State, rhs: State) -> Bool {

Sources/SwiftNetwork/Path/Interface.swift

@@ -19,35 +19,35 @@ internal import Logging
 internal import os
 #endif
 
-/// Interface types represent the underlying media for a network link
+/// The type of underlying media for a network link.
 @_spi(Essentials)
 @available(Network 0.1.0, *)
 public enum InterfaceType: Int, Sendable, CaseIterable {
-    /// A virtual or otherwise unknown interface type
+    /// A virtual or otherwise unknown interface type.
     case other = 0
-    /// A Wi-Fi link
+    /// A Wi-Fi link.
     case wifi = 2
-    /// A Cellular link
+    /// A cellular link.
     case cellular = 3
-    /// A Wired Ethernet link
+    /// A wired Ethernet link.
     case wiredEthernet = 4
-    /// The Loopback Interface
+    /// The loopback interface.
     case loopback = 1
 }
 
-/// Interface subtypes represent the underlying media subtype for a network link
+/// The subtype of underlying media for a network link.
 @_spi(Essentials)
 @available(Network 0.1.0, *)
 public enum InterfaceSubtype: Int, Sendable, CaseIterable {
-    /// A virtual or otherwise unknown interface subtype
+    /// A virtual or otherwise unknown interface subtype.
     case other = 0
-    /// A Wi-Fi Infrastructure subtype
+    /// A Wi-Fi infrastructure subtype.
     case wifiInfrastructure = 3
-    /// A Wi-Fi AWDL subtype
+    /// A Wi-Fi AWDL subtype.
     case wifiAWDL = 4
-    /// A Coprocessor subtype
+    /// A coprocessor subtype.
     case coprocessor = 6
-    /// A Companion subtype
+    /// A companion subtype.
     case companion = 7
 }
 

Sources/SwiftNetwork/Path/PathProperties.swift

@@ -244,15 +244,15 @@ public struct PathProperties: CustomStringConvertible {
         static public let fallbackIsOpportunistic = Flags(rawValue: 1 << 33)
     }
 
-    /// Represents the link quality measurement of the link layer network attachment
+    /// The link quality measurement of the link-layer network attachment.
     public enum LinkQuality: Sendable {
-        /// No link quality measurement is available
+        /// No link quality measurement is available.
         case unknown
-        /// Link quality is bad
+        /// The link quality is minimal.
         case minimal
-        /// Link quality is moderate
+        /// The link quality is moderate.
         case moderate
-        /// Link quality is good
+        /// The link quality is good.
         case good
 
         internal init(_ nw: Int8) {