Light edit on guides and sequence source docs (rdar://90176127) (#86)

* Light-touch edit on existing guides.

* Light edit on the sequences' source docs.

Co-authored-by: Chris Adamson <[email protected]>

Author: invalidname

Guides/BufferedBytes.md

@@ -40,13 +40,13 @@ public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
 }
 ```
 
-For each invocation of `next` the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled then the read function is invoked to acquire the next filled buffer and then it takes a byte out of that buffer.
+For each invocation of `next`, the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes, a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled, the read function is invoked to acquire the next filled buffer, at which point it takes a byte out of that buffer.
 
-If the read function returns 0 indicating it read no more bytes the iterator is claimed to be finished and no additional invocations to the read function are made.
+If the read function returns `0`, indicating it didn't read any more bytes, the iterator is decided to be finished and no additional invocations to the read function are made.
 
-If the read function throws the error will be thrown by the iteration. Subsequent invocations to the iterator will return nil without invoking the read function.
+If the read function throws, the error will be thrown by the iteration. Subsequent invocations to the iterator will then return `nil` without invoking the read function.
 
-During the iteration if the task is cancelled the iteration will check the cancellation only in passes where the read function is invoked and will throw a `CancellationError`.
+If the task is cancelled during the iteration, the iteration will check the cancellation only in passes where the read function is invoked, and will throw a `CancellationError`.
 
 ### Naming
 

Guides/Chain.md

@@ -20,11 +20,11 @@ for try await line in lines {
 }
 ```
 
-The above example shows how two `AsyncSequence` types can be chained together. In this case it prepends a preamble to the lines content of the file. 
+The above example shows how two `AsyncSequence` types can be chained together. In this case it prepends a preamble to the `lines` content of the file. 
 
 ## Detailed Design
 
-This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted these will be implemented in terms of two and three base sequence cases.
+This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
 
 ```swift
 public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element
@@ -62,12 +62,12 @@ The `chain(_:...)` function takes two or more sequences as arguments.
 
 The resulting `AsyncChainSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments conform.
 
-When any of the asynchronous sequences being chained together come to their end of iteration the `AsyncChainSequence` iteration proceeds on to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration the `AsyncChainSequence` then ends its iteration. At any point in time if one of the comprising asynchronous sequences ever throw an error during iteration the resulting `AsyncChainSequence` iteration will throw that error and end iteration.
+When any of the asynchronous sequences being chained together come to their end of iteration, the `AsyncChainSequence` iteration proceeds to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration, the `AsyncChainSequence` then ends its iteration. 
 
-The throwing behavior of `AsyncChainSequence` is that it will throw when any of its comprising bases throw, and will not throw when all of its comprising bases do not throw.
+At any point in time, if one of the comprising asynchronous sequences throws an error during iteration, the resulting `AsyncChainSequence` iteration will throw that error and end iteration. The throwing behavior of `AsyncChainSequence` is that it will throw when any of its comprising bases throw, and will not throw when all of its comprising bases do not throw.
 
 ### Naming
 
 This function's and type's name match the term of art used in other languages and libraries.
 
-This combinator function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md).
+This combinator function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md).

Guides/CombineLatest.md

@@ -25,7 +25,7 @@ Given some sample inputs the following combined events can be expected.
 
 ## Detailed Design
 
-This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted these will be implemented in terms of two and three base sequence cases.
+This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
 
 ```swift
 public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2>
@@ -62,13 +62,13 @@ public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequ
 
 ```
 
-The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncCombineLatestSequence` which is an asynchronous sequence.
+The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments and produces an  `AsyncCombineLatestSequence` which is an asynchronous sequence.
 
-Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value it means that those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elemnts they produce must be `Sendable`. 
+Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elemnts they produce must all be `Sendable`. 
 
-If any of the bases terminate before the first element is produced then the `AsyncCombineLatestSequence` iteration can never be satisfied so if a base's iterator returns nil at the first iteration then the `AsyncCombineLatestSequence` iterator immediately returns nil to signify a terminal state. In this particular case any outstanding iteration of other bases will be cancelled. After the first element is produced this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the base the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
+If any of the bases terminate before the first element is produced, then the `AsyncCombineLatestSequence` iteration can never be satisfied. So, if a base's iterator returns `nil` at the first iteration, then the `AsyncCombineLatestSequence` iterator immediately returns `nil` to signify a terminal state. In this particular case, any outstanding iteration of other bases will be cancelled. After the first element is produced ,this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the bases, the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
 
-The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw then the composed asynchronous sequence then throws on its iteration. If at any point (within the first or afterwards) an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
+The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point (within the first iteration or afterwards), an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
 
 ### Naming
 

Guides/Intersperse.md

@@ -3,7 +3,7 @@
 [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncInterspersedSequence.swift) | 
  [Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestInterspersed.swift)]
 
-Place a given value in between each element of the asynchronous sequence.
+Places a given value in between each element of the asynchronous sequence.
 
 ```swift
 let numbers = [1, 2, 3].async.interspersed(with: 0)
@@ -32,9 +32,9 @@ extension AsyncSequence {
 The new `AsyncInterspersedSequence` type represents the asynchronous sequence 
 when the separator is inserted between each element. 
 
-When the base asynchronous sequence can throw on iteration `AsyncInterspersedSequence`
-will throw on iteration; when the base does not throw then the iteration of 
-`AsyncInterspersedSequence` does not.
+When the base asynchronous sequence can throw on iteration, `AsyncInterspersedSequence`
+will throw on iteration. When the base does not throw, the iteration of 
+`AsyncInterspersedSequence` does not throw either.
 
 `AsyncInterspersedSequence` is conditionally `Sendable` when the base asynchronous
 sequence is `Sendable` and the element is also `Sendable`.

Guides/Lazy.md

@@ -3,7 +3,7 @@
 [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncLazySequence.swift) | 
 [Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)]
 
-Converts a non asynchronous sequence into an asynchronous one. 
+Converts a non-asynchronous sequence into an asynchronous one. 
 
 This operation is available for all `Sequence` types. 
 
@@ -17,7 +17,7 @@ to combine with other `AsyncSequence` types to provide well known sources of dat
 
 ## Detailed Design
 
-The `.async` property is returns an `AsyncLazySequence` that is generic upon the base `Sequence` it was constructed from.
+The `.async` property returns an `AsyncLazySequence` that is generic upon the base `Sequence` it was constructed from.
 
 ```swift
 extension Sequence {

Guides/Merge.md

@@ -25,7 +25,7 @@ Given some sample inputs the following merged events can be expected.
 
 ## Detailed Design
 
-This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted these will be implemented in terms of two and three base sequence cases.
+This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
 
 ```swift
 public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
@@ -64,17 +64,17 @@ public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Ba
 
 ```
 
-The `merge(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncMergeSequence` which is an asynchronous sequence.
+The `merge(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncMergeSequence` which is an asynchronous sequence.
 
-Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value it means that those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`. 
+Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value,  those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`. 
 
-When iterating a `AsyncMergeSequence` it becomes terminal when all of the base asynchronous sequences are terminal; meaning there is no more potential of any elements being produced. 
+When iterating a `AsyncMergeSequence`, the sequence terminates when all of the base asynchronous sequences terminate, since this means there is no potential for any further elements to be produced. 
 
-The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw then the composed asynchronous sequence then throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
+The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
 
 ### Naming
 
-Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
+Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence, the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
 
 ### Comparison with other libraries