Label the output and input ends of Signal.pipe()

Attempts to clarify usage by being more explicit about the input and
output ends of the signal "pipe", and rewords the documentation accordingly.

See also: https://swift.org/documentation/api-design-guidelines/#label-closure-parameters.

Author: sharplet

Sources/Signal.swift

@@ -265,19 +265,20 @@ public final class Signal<Value, Error: Swift.Error> {
 		}
 	}
 
-	/// Create a Signal that will be controlled by sending events to the given
-	/// observer.
+	/// Create a `Signal` that will be controlled by sending events to an
+	/// input observer.
 	///
-	/// - note: The Signal will remain alive until a terminating event is sent
-	///         to the observer, or until it has no observer if it is not
-	///         retained.
+	/// - note: The `Signal` will remain alive until a terminating event is sent
+	///         to the input observer, or until it has no observers and there
+	///         are no strong references to it.
 	///
 	/// - parameters:
 	///   - disposable: An optional disposable to associate with the signal, and
 	///                 to be disposed of when the signal terminates.
 	///
-	/// - returns: A tuple made of signal and observer.
-	public static func pipe(disposable: Disposable? = nil) -> (Signal, Observer) {
+	/// - returns: A tuple of `output: Signal`, the output end of the pipe,
+	///            and `input: Observer`, the input end of the pipe.
+	public static func pipe(disposable: Disposable? = nil) -> (output: Signal, input: Observer) {
 		var observer: Observer!
 		let signal = self.init { innerObserver in
 			observer = innerObserver

Tests/ReactiveSwiftTests/FlattenSpec.swift

@@ -12,7 +12,7 @@ import Quick
 import ReactiveSwift
 
 private extension SignalProtocol {
-	typealias Pipe = (signal: Signal<Value, Error>, observer: Observer<Value, Error>)
+	typealias Pipe = (output: Signal<Value, Error>, input: Observer<Value, Error>)
 }
 
 private typealias Pipe = Signal<SignalProducer<Int, TestError>, TestError>.Pipe
@@ -26,7 +26,7 @@ class FlattenSpec: QuickSpec {
 
 				beforeEach {
 					pipe = Signal.pipe()
-					disposable = pipe.signal
+					disposable = pipe.output
 						.flatten(flattenStrategy)
 						.observe { _ in }
 				}
@@ -40,25 +40,25 @@ class FlattenSpec: QuickSpec {
 
 					beforeEach {
 						disposed = false
-						pipe.observer.send(value: SignalProducer<Int, TestError> { _, disposable in
+						pipe.input.send(value: SignalProducer<Int, TestError> { _, disposable in
 							disposable += ActionDisposable {
 								disposed = true
 							}
 						})
 					}
 
 					it("should dispose inner signals when outer signal interrupted") {
-						pipe.observer.sendInterrupted()
+						pipe.input.sendInterrupted()
 						expect(disposed) == true
 					}
 
 					it("should dispose inner signals when outer signal failed") {
-						pipe.observer.send(error: .default)
+						pipe.input.send(error: .default)
 						expect(disposed) == true
 					}
 
 					it("should not dispose inner signals when outer signal completed") {
-						pipe.observer.sendCompleted()
+						pipe.input.sendCompleted()
 						expect(disposed) == false
 					}
 				}