Apply documetation suggestions from code review

Co-authored-by: Joseph Heck <[email protected]>

Author: iCharlesHu

Sources/Subprocess/API.swift

@@ -17,8 +17,8 @@
 
 // MARK: - Collected Result
 
-/// Run an executable with given parameters asynchronously and returns a
-/// `CollectedResult` containing the output of the child process.
+/// Run an executable with given parameters asynchronously and return a
+/// collected result that contains the output of the child process.
 /// - Parameters:
 ///   - executable: The executable to run.
 ///   - arguments: The arguments to pass to the executable.
@@ -59,8 +59,8 @@ public func run<
 }
 
 #if SubprocessSpan
-/// Run an executable with given parameters asynchronously and returns a
-/// `CollectedResult` containing the output of the child process.
+/// Run an executable with given parameters asynchronously and return a
+/// collected result that contains the output of the child process.
 /// - Parameters:
 ///   - executable: The executable to run.
 ///   - arguments: The arguments to pass to the executable.

Sources/Subprocess/AsyncBufferSequence.swift

@@ -19,11 +19,11 @@
 internal import Dispatch
 #endif
 
-/// A synchronous sequence of `Buffer`s used to stream output from subprocess.
+/// A synchronous sequence of buffers used to stream output from subprocess.
 public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
-    /// The failure type for this `AsyncSequence`
+    /// The failure type for the asynchronous sequence.
     public typealias Failure = any Swift.Error
-    /// The element type for this `AsyncSequence`
+    /// The element type for the asynchronous sequence.
     public typealias Element = Buffer
 
     #if SUBPROCESS_ASYNCIO_DISPATCH
@@ -37,7 +37,7 @@ public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
     /// Iterator for `AsyncBufferSequence`.
     @_nonSendable
     public struct Iterator: AsyncIteratorProtocol {
-        /// The element type for this iterator
+        /// The element type for the iterator.
         public typealias Element = Buffer
 
         private let diskIO: DiskIO
@@ -48,8 +48,8 @@ public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
             self.buffer = []
         }
 
-        /// Retrieve the next `Buffer` in the sequence, nor `nil` if
-        /// the sequence has ended,
+        /// Retrieve the next buffer in the sequence, or `nil` if
+        /// the sequence has ended.
         public mutating func next() async throws -> Buffer? {
             // If we have more left in buffer, use that
             guard self.buffer.isEmpty else {
@@ -89,12 +89,12 @@ public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
         self.diskIO = diskIO
     }
 
-    /// Creates a iterator for this `AsyncSequence`
+    /// Creates a iterator for this asynchronous sequence.
     public func makeAsyncIterator() -> Iterator {
         return Iterator(diskIO: self.diskIO)
     }
 
-    /// Creates a line sequence to iterate through this `AsyncBufferSequence` line by line
+    /// Creates a line sequence to iterate through this `AsyncBufferSequence` line by line.
     public func lines() -> LineSequence<UTF8> {
         return LineSequence(
             underlying: self,
@@ -103,7 +103,7 @@ public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
         )
     }
 
-    /// Creates a line sequence to iterate through this `AsyncBufferSequence` line by line
+    /// Creates a line sequence to iterate through a `AsyncBufferSequence` line by line.
     /// - Parameters:
     ///   - encoding: The taget encoding to encoding Strings to
     ///   - bufferingPolicy: How should back-pressure be handled
@@ -118,19 +118,19 @@ public struct AsyncBufferSequence: AsyncSequence, @unchecked Sendable {
 
 // MARK: - LineSequence
 extension AsyncBufferSequence {
-    /// An asynchronous sequence of `String` which each String representing a line
-    /// `LineSequence` parses and splits `AsyncBufferSequence` into lines. It is the
-    /// preferred method to convert `Buffer` to `String`
+    /// Line sequence parses and splits an asynchronous sequence of buffers into lines.
+    ///
+    /// It is the preferred method to convert `Buffer` to `String`
     public struct LineSequence<Encoding: _UnicodeEncoding>: AsyncSequence, Sendable {
-        /// The element type for this `AsyncSequence`
+        /// The element type for the asynchronous sequence.
         public typealias Element = String
 
         private let base: AsyncBufferSequence
         private let bufferingPolicy: BufferingPolicy
 
-        /// The iterator for `LineSequence`
+        /// The iterator for line sequence.
         public struct AsyncIterator: AsyncIteratorProtocol {
-            /// The element type for this Iterator
+            /// The element type for this Iterator.
             public typealias Element = String
 
             private var source: AsyncBufferSequence.AsyncIterator
@@ -152,7 +152,7 @@ extension AsyncBufferSequence {
                 self.bufferingPolicy = bufferingPolicy
             }
 
-            /// Retrieve the next line
+            /// Retrieves the next line, or returns nil if the sequence ends.
             public mutating func next() async throws -> String? {
 
                 func loadBuffer() async throws -> [Encoding.CodeUnit]? {
@@ -327,7 +327,7 @@ extension AsyncBufferSequence {
             }
         }
 
-        /// Creates a iterator for this `LineSequence`
+        /// Creates a iterator for this line sequence.
         public func makeAsyncIterator() -> AsyncIterator {
             return AsyncIterator(
                 underlyingIterator: self.base.makeAsyncIterator(),
@@ -347,7 +347,7 @@ extension AsyncBufferSequence {
 }
 
 extension AsyncBufferSequence.LineSequence {
-    /// A strategy that handles exhaustion of a buffer’s capacity.
+    /// A strategy that handles the exhaustion of a buffer’s capacity.
     public enum BufferingPolicy: Sendable {
         /// Continue to add to the buffer, without imposing a limit
         /// on the number of buffered elements (line length).

Sources/Subprocess/Buffer.swift

@@ -95,7 +95,7 @@ extension AsyncBufferSequence.Buffer {
 // MARK: - Hashable, Equatable
 extension AsyncBufferSequence.Buffer: Equatable, Hashable {
     #if SUBPROCESS_ASYNCIO_DISPATCH
-    /// Returns a Boolean value indicating whether two `AsyncBufferSequence.Buffer`s are equal.
+    /// Returns a Boolean value that indicates whether two buffers are equal.
     public static func == (lhs: AsyncBufferSequence.Buffer, rhs: AsyncBufferSequence.Buffer) -> Bool {
         return lhs.data == rhs.data
     }

Sources/Subprocess/Configuration.swift

@@ -41,14 +41,15 @@ public struct Configuration: Sendable {
     /// The environment to use when running the executable.
     public var environment: Environment
     /// The working directory to use when running the executable.
+    ///
     /// If this property is `nil`, the subprocess will inherit
     /// the working directory from the parent process.
     public var workingDirectory: FilePath?
     /// The platform specific options to use when
     /// running the subprocess.
     public var platformOptions: PlatformOptions
 
-    /// Creates a Configuration with the given parameters
+    /// Creates a Configuration with the parameters you provide.
     /// - Parameters:
     ///   - executable: the executable to run
     ///   - arguments: the arguments to pass to the executable.
@@ -127,7 +128,7 @@ public struct Configuration: Sendable {
 }
 
 extension Configuration: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `Configuration`.
+    /// A textual representation of this configuration.
     public var description: String {
         return """
             Configuration(
@@ -140,7 +141,7 @@ extension Configuration: CustomStringConvertible, CustomDebugStringConvertible {
             """
     }
 
-    /// A textual representation of this `Configuration`.
+    /// A debug-oriented textual representation of this configuration.
     public var debugDescription: String {
         return """
             Configuration(
@@ -208,8 +209,7 @@ extension Configuration {
 
 // MARK: - Executable
 
-/// Executable defines how the executable should be
-/// looked up for execution.
+/// Executable defines how subprocess looks up the executable for execution.
 public struct Executable: Sendable, Hashable {
     internal enum Storage: Sendable, Hashable {
         case executable(String)
@@ -241,7 +241,7 @@ public struct Executable: Sendable, Hashable {
 }
 
 extension Executable: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `Executable`.
+    /// A textual representation of this executable.
     public var description: String {
         switch storage {
         case .executable(let executableName):
@@ -251,7 +251,7 @@ extension Executable: CustomStringConvertible, CustomDebugStringConvertible {
         }
     }
 
-    /// A textual representation of this `Executable`.
+    /// A debug-oriented textual representation of this executable.
     public var debugDescription: String {
         switch storage {
         case .executable(let string):
@@ -316,7 +316,7 @@ public struct Arguments: Sendable, ExpressibleByArrayLiteral, Hashable {
             self.executablePathOverride = nil
         }
     }
-    /// Create an Arguments object using the given array
+    /// Create an arguments object using the array you provide.
     public init(_ array: [[UInt8]]) {
         self.storage = array.map { .rawBytes($0) }
         self.executablePathOverride = nil
@@ -325,7 +325,7 @@ public struct Arguments: Sendable, ExpressibleByArrayLiteral, Hashable {
 }
 
 extension Arguments: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `Arguments`.
+    /// A textual representation of the arguments.
     public var description: String {
         var result: [String] = self.storage.map(\.description)
 
@@ -335,7 +335,7 @@ extension Arguments: CustomStringConvertible, CustomDebugStringConvertible {
         return result.description
     }
 
-    /// A textual representation of this `Arguments`.
+    /// A debug-oriented textual representation of the arguments.
     public var debugDescription: String { return self.description }
 }
 
@@ -379,7 +379,7 @@ public struct Environment: Sendable, Hashable {
 }
 
 extension Environment: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `Environment`.
+    /// A textual representation of the environment.
     public var description: String {
         switch self.config {
         case .custom(let customDictionary):
@@ -402,7 +402,7 @@ extension Environment: CustomStringConvertible, CustomDebugStringConvertible {
         }
     }
 
-    /// A textual representation of this `Environment`.
+    /// A debug-oriented textual representation of the environment.
     public var debugDescription: String {
         return self.description
     }
@@ -440,14 +440,14 @@ extension Environment: CustomStringConvertible, CustomDebugStringConvertible {
 
 // MARK: - TerminationStatus
 
-/// An exit status of a subprocess
+/// An exit status of a subprocess.
 @frozen
 public enum TerminationStatus: Sendable, Hashable {
     #if canImport(WinSDK)
-    /// The type of status code
+    /// The type of the status code.
     public typealias Code = DWORD
     #else
-    /// The type of status code
+    /// The type of the status code.
     public typealias Code = CInt
     #endif
 
@@ -467,7 +467,7 @@ public enum TerminationStatus: Sendable, Hashable {
 }
 
 extension TerminationStatus: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `TerminationStatus`.
+    /// A textual representation of this termination status.
     public var description: String {
         switch self {
         case .exited(let code):
@@ -477,7 +477,7 @@ extension TerminationStatus: CustomStringConvertible, CustomDebugStringConvertib
         }
     }
 
-    /// A textual representation of this `TerminationStatus`.
+    /// A debug-oriented textual representation of this termination status.
     public var debugDescription: String {
         return self.description
     }
@@ -651,9 +651,11 @@ internal func _safelyClose(_ target: _CloseTarget) throws {
     }
 }
 
-/// IODescriptor wraps platform-specific FileDescriptor, which is used to establish a
+/// An IO descriptor wraps platform-specific file descriptor, which establishes a
 /// connection to the standard input/output (IO) system during the process of
-/// spawning a child process. Unlike IODescriptor, the IODescriptor does not support
+/// spawning a child process. 
+///
+/// Unlike a file descriptor, the `IODescriptor` does not support
 /// data read/write operations; its primary function is to facilitate the spawning of
 /// child processes by providing a platform-specific file descriptor.
 internal struct IODescriptor: ~Copyable {
@@ -965,10 +967,12 @@ extension Optional where Wrapped == String {
     }
 }
 
-/// Runs `body`, and then runs `onCleanup` if `body` throws an error,
-/// or if the parent task is cancelled. In the latter case, `onCleanup`
-/// may be run concurrently with `body`. `body` is guaranteed to run exactly once.
-/// `onCleanup` is guaranteed to run only once, or not at all.
+/// Runs the body close, then runs the on-cleanup closure if the body closure throws an error
+/// or if the parent task is cancelled.
+///
+/// In the latter case, `onCleanup` may be run concurrently with `body`. 
+/// The `body` closure is guaranteed to run exactly once.
+/// The `onCleanup` closure is guaranteed to run only once, or not at all.
 internal func withAsyncTaskCleanupHandler<Result>(
     _ body: () async throws -> Result,
     onCleanup handler: @Sendable @escaping () async -> Void,

Sources/Subprocess/Error.swift

@@ -53,7 +53,7 @@ extension SubprocessError {
             case invalidWindowsPath(String)
         }
 
-        /// The numeric value of this `Code`
+        /// The numeric value of this code.
         public var value: Int {
             switch self.storage {
             case .spawnFailed:
@@ -99,7 +99,7 @@ extension SubprocessError {
 
 // MARK: - Description
 extension SubprocessError: CustomStringConvertible, CustomDebugStringConvertible {
-    /// A textual representation of this `SubprocessError`.
+    /// A textual representation of this subprocess error.
     public var description: String {
         switch self.code.storage {
         case .spawnFailed:
@@ -135,7 +135,7 @@ extension SubprocessError: CustomStringConvertible, CustomDebugStringConvertible
         }
     }
 
-    /// A textual representation of this `SubprocessError`.
+    /// A debug-oriented textual representation of this subprocess error.
     public var debugDescription: String { self.description }
 }
 
@@ -145,14 +145,14 @@ extension SubprocessError {
     /// - On Windows, `UnderlyingError` wraps Windows Error code
     public struct UnderlyingError: Swift.Error, RawRepresentable, Hashable, Sendable {
         #if os(Windows)
-        /// The type of raw value for this UnderlyingError
+        /// The type for the raw value of the underlying error.
         public typealias RawValue = DWORD
         #else
-        /// The type of raw value for this UnderlyingError
+        /// The type for the raw value of the underlying error.
         public typealias RawValue = Int32
         #endif
 
-        /// The platform specific value for this `UnderlyingError`
+        /// The platform specific value for this underlying error.
         public let rawValue: RawValue
         /// Initialize a `UnderlyingError` with given error value
         public init(rawValue: RawValue) {