diff --git a/Sources/Atomic.swift b/Sources/Atomic.swift index 8a2be7741..be7a665fc 100644 --- a/Sources/Atomic.swift +++ b/Sources/Atomic.swift @@ -21,6 +21,7 @@ internal protocol AtomicStateProtocol { /// /// - parameters: /// - expected: The expected state. + /// - next: The state to transition to. /// /// - returns: /// `true` if the transition succeeds. `false` otherwise. @@ -69,6 +70,7 @@ internal struct UnsafeAtomicState: AtomicStateProtocol /// /// - parameters: /// - expected: The expected state. + /// - next: The state to transition to. /// /// - returns: /// `true` if the transition succeeds. `false` otherwise. diff --git a/Sources/Disposable.swift b/Sources/Disposable.swift index 806ed113d..d9da8608e 100644 --- a/Sources/Disposable.swift +++ b/Sources/Disposable.swift @@ -112,7 +112,10 @@ public final class CompositeDisposable: Disposable { private var state: UnsafeAtomicState /// Represents a handle to a disposable previously added to a - /// CompositeDisposable. + /// `CompositeDisposable`. + /// + /// - note: `add(_:)` method of `CompositeDisposable` creates instances of + /// `DisposableHandle`. public final class DisposableHandle { private var state: UnsafeAtomicState private var bagToken: RemovalToken? diff --git a/Sources/Flatten.swift b/Sources/Flatten.swift index 0adb04cd5..4d6f8ef61 100644 --- a/Sources/Flatten.swift +++ b/Sources/Flatten.swift @@ -41,8 +41,11 @@ extension SignalProtocol where Value: SignalProducerProtocol, Error == Value.Err /// - note: If `signal` or an active inner producer fails, the returned /// signal will forward that failure immediately. /// - /// - note: `interrupted` events on inner producers will be treated like - /// `Completed events on inner producers. + /// - warning: `interrupted` events on inner producers will be treated like + /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { switch strategy { case .merge: @@ -61,8 +64,8 @@ extension SignalProtocol where Value: SignalProducerProtocol, Error == NoError { /// Flattens the inner producers sent upon `signal` (into a single signal of /// values), according to the semantics of the given strategy. /// - /// - note: If an active inner producer fails, the returned signal will - /// forward that failure immediately. + /// - note: If `signal` or an active inner producer fails, the returned + /// signal will forward that failure immediately. /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. @@ -108,6 +111,9 @@ extension SignalProtocol where Value: SignalProducerProtocol, Value.Error == NoE /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self.flatMap(strategy) { $0.promoteErrors(Error.self) } } @@ -122,6 +128,9 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == V /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { switch strategy { case .merge: @@ -145,6 +154,9 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == N /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self .promoteErrors(Value.Error.self) @@ -158,6 +170,9 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == N /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { switch strategy { case .merge: @@ -181,6 +196,9 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Value.Erro /// /// - warning: `interrupted` events on inner producers will be treated like /// `completed` events on inner producers. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self.flatMap(strategy) { $0.promoteErrors(Error.self) } } @@ -195,6 +213,9 @@ extension SignalProtocol where Value: SignalProtocol, Error == Value.Error { /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self .map(SignalProducer.init) @@ -211,6 +232,9 @@ extension SignalProtocol where Value: SignalProtocol, Error == NoError { /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self .promoteErrors(Value.Error.self) @@ -224,6 +248,9 @@ extension SignalProtocol where Value: SignalProtocol, Error == NoError, Value.Er /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self .map(SignalProducer.init) @@ -240,6 +267,9 @@ extension SignalProtocol where Value: SignalProtocol, Value.Error == NoError { /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self.flatMap(strategy) { $0.promoteErrors(Error.self) } } @@ -261,6 +291,9 @@ extension SignalProducerProtocol where Value: SignalProtocol, Error == Value.Err /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self .map(SignalProducer.init) @@ -277,6 +310,9 @@ extension SignalProducerProtocol where Value: SignalProtocol, Error == NoError { /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self .promoteErrors(Value.Error.self) @@ -290,6 +326,9 @@ extension SignalProducerProtocol where Value: SignalProtocol, Error == NoError, /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self .map(SignalProducer.init) @@ -306,6 +345,9 @@ extension SignalProducerProtocol where Value: SignalProtocol, Value.Error == NoE /// /// - warning: `interrupted` events on inner signals will be treated like /// `completed` events on inner signals. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self.flatMap(strategy) { $0.promoteErrors(Error.self) } } @@ -324,6 +366,9 @@ extension SignalProtocol where Value: PropertyProtocol { /// /// - note: If `signal` fails, the returned signal will forward that failure /// immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> Signal { return self.flatMap(strategy) { $0.producer } } @@ -335,6 +380,9 @@ extension SignalProducerProtocol where Value: PropertyProtocol { /// /// - note: If `signal` fails, the returned signal will forward that failure /// immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. public func flatten(_ strategy: FlattenStrategy) -> SignalProducer { return self.flatMap(strategy) { $0.producer } } @@ -437,16 +485,34 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == V extension SignalProducerProtocol { /// `concat`s `next` onto `self`. + /// + /// - parameters: + /// - next: A follow-up producer to concat `self` with. + /// + /// - returns: A producer that will start `self` and then on completion of + /// `self` - will start `next`. public func concat(_ next: SignalProducer) -> SignalProducer { return SignalProducer, Error>([ self.producer, next ]).flatten(.concat) } /// `concat`s `value` onto `self`. + /// + /// - parameters: + /// - value: A value to concat onto `self`. + /// + /// - returns: A producer that, when started, will emit own values and on + /// completion will emit a `value`. public func concat(value: Value) -> SignalProducer { return self.concat(SignalProducer(value: value)) } /// `concat`s `self` onto initial `previous`. + /// + /// - parameters: + /// - previous: A producer to start before `self`. + /// + /// - returns: A signal producer that, when started, first emits values from + /// `previous` producer and then from `self`. public func prefix(_ previous: P) -> SignalProducer where P.Value == Value, P.Error == Error { @@ -454,6 +520,12 @@ extension SignalProducerProtocol { } /// `concat`s `self` onto initial `value`. + /// + /// - parameters: + /// - value: A first value to emit. + /// + /// - returns: A producer that, when started, first emits `value`, then all + /// values emited by `self`. public func prefix(value: Value) -> SignalProducer { return self.prefix(SignalProducer(value: value)) } @@ -573,6 +645,9 @@ extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == V extension SignalProtocol { /// Merges the given signals into a single `Signal` that will emit all /// values from each of them, and complete when all of them have completed. + /// + /// - parameters: + /// - signals: A sequence of signals to merge. public static func merge(_ signals: Seq) -> Signal where S.Value == Value, S.Error == Error, Seq.Iterator.Element == S { @@ -583,6 +658,9 @@ extension SignalProtocol { /// Merges the given signals into a single `Signal` that will emit all /// values from each of them, and complete when all of them have completed. + /// + /// - parameters: + /// - signals: A list of signals to merge. public static func merge(_ signals: S...) -> Signal where S.Value == Value, S.Error == Error { @@ -594,6 +672,9 @@ extension SignalProducerProtocol { /// Merges the given producers into a single `SignalProducer` that will emit /// all values from each of them, and complete when all of them have /// completed. + /// + /// - parameters: + /// - producers: A sequence of producers to merge. public static func merge(_ producers: Seq) -> SignalProducer where S.Value == Value, S.Error == Error, Seq.Iterator.Element == S { @@ -603,6 +684,9 @@ extension SignalProducerProtocol { /// Merges the given producers into a single `SignalProducer` that will emit /// all values from each of them, and complete when all of them have /// completed. + /// + /// - parameters: + /// - producers: A sequence of producers to merge. public static func merge(_ producers: S...) -> SignalProducer where S.Value == Value, S.Error == Error { @@ -614,11 +698,11 @@ extension SignalProtocol where Value: SignalProducerProtocol, Error == Value.Err /// Returns a signal that forwards values from the latest signal sent on /// `signal`, ignoring values sent on previous inner signal. /// - /// An error sent on `signal` or the latest inner signal will be sent on the - /// returned signal. + /// - warning: An error sent on `signal` or the latest inner signal will be + /// sent on the returned signal. /// - /// The returned signal completes when `signal` and the latest inner - /// signal have both completed. + /// - note: The returned signal completes when `signal` and the latest inner + /// signal have both completed. fileprivate func switchToLatest() -> Signal { return Signal { observer in let composite = CompositeDisposable() @@ -705,14 +789,14 @@ extension SignalProtocol where Value: SignalProducerProtocol, Error == Value.Err } extension SignalProducerProtocol where Value: SignalProducerProtocol, Error == Value.Error { - /// Returns a signal that forwards values from the latest signal sent on - /// `signal`, ignoring values sent on previous inner signal. + /// - warning: An error sent on `signal` or the latest inner signal will be + /// sent on the returned signal. /// - /// An error sent on `signal` or the latest inner signal will be sent on the - /// returned signal. + /// - note: The returned signal completes when `signal` and the latest inner + /// signal have both completed. /// - /// The returned signal completes when `signal` and the latest inner - /// signal have both completed. + /// - returns: A signal that forwards values from the latest signal sent on + /// `signal`, ignoring values sent on previous inner signal. fileprivate func switchToLatest() -> SignalProducer { return SignalProducer { observer, disposable in let latestInnerDisposable = SerialDisposable() @@ -739,8 +823,13 @@ extension SignalProtocol { /// resulting producers (into a signal of values), according to the /// semantics of the given strategy. /// - /// If `signal` or any of the created producers fail, the returned signal - /// will forward that failure immediately. + /// - warning: If `signal` or any of the created producers fail, the + /// returned signal will forward that failure immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> Signal { return map(transform).flatten(strategy) } @@ -749,8 +838,13 @@ extension SignalProtocol { /// resulting producers (into a signal of values), according to the /// semantics of the given strategy. /// - /// If `signal` fails, the returned signal will forward that failure - /// immediately. + /// - warning: If `signal` fails, the returned signal will forward that + /// failure immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> Signal { return map(transform).flatten(strategy) } @@ -759,8 +853,13 @@ extension SignalProtocol { /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. /// - /// If `signal` or any of the created signals emit an error, the returned - /// signal will forward that error immediately. + /// - warning: If `signal` or any of the created signals emit an error, the + /// returned signal will forward that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> Signal { return map(transform).flatten(strategy) } @@ -769,8 +868,13 @@ extension SignalProtocol { /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. /// - /// If `signal` emits an error, the returned signal will forward that - /// error immediately. + /// - warning: If `signal` emits an error, the returned signal will forward + /// that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> Signal { return map(transform).flatten(strategy) } @@ -779,8 +883,13 @@ extension SignalProtocol { /// resulting properties (into a signal of values), according to the /// semantics of the given strategy. /// - /// If `signal` emits an error, the returned signal will forward that - /// error immediately. + /// - warning: If `signal` emits an error, the returned signal will forward + /// that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a property with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> P) -> Signal { return map(transform).flatten(strategy) } @@ -791,8 +900,13 @@ extension SignalProtocol where Error == NoError { /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. /// - /// If any of the created signals emit an error, the returned signal - /// will forward that error immediately. + /// - warning: If any of the created signals emit an error, the returned + /// signal will forward that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> Signal { return map(transform).flatten(strategy) } @@ -800,6 +914,11 @@ extension SignalProtocol where Error == NoError { /// Maps each event from `signal` to a new signal, then flattens the /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> Signal { return map(transform).flatten(strategy) } @@ -808,8 +927,13 @@ extension SignalProtocol where Error == NoError { /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. /// - /// If any of the created signals emit an error, the returned signal - /// will forward that error immediately. + /// - warning: If any of the created signals emit an error, the returned + /// signal will forward that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> Signal { return map(transform).flatten(strategy) } @@ -817,6 +941,11 @@ extension SignalProtocol where Error == NoError { /// Maps each event from `signal` to a new signal, then flattens the /// resulting signals (into a signal of values), according to the /// semantics of the given strategy. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> Signal { return map(transform).flatten(strategy) } @@ -827,8 +956,13 @@ extension SignalProducerProtocol { /// resulting producers (into a producer of values), according to the /// semantics of the given strategy. /// - /// If `self` or any of the created producers fail, the returned producer - /// will forward that failure immediately. + /// - warning: If `self` or any of the created producers fail, the returned + /// producer will forward that failure immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> SignalProducer { return map(transform).flatten(strategy) } @@ -837,8 +971,13 @@ extension SignalProducerProtocol { /// resulting producers (into a producer of values), according to the /// semantics of the given strategy. /// - /// If `self` fails, the returned producer will forward that failure - /// immediately. + /// - warning: If `self` fails, the returned producer will forward that + /// failure immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> SignalProducer { return map(transform).flatten(strategy) } @@ -847,8 +986,13 @@ extension SignalProducerProtocol { /// resulting signals (into a producer of values), according to the /// semantics of the given strategy. /// - /// If `self` or any of the created signals emit an error, the returned - /// producer will forward that error immediately. + /// - warning: If `self` or any of the created signals emit an error, the + /// returned producer will forward that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> SignalProducer { return map(transform).flatten(strategy) } @@ -857,8 +1001,13 @@ extension SignalProducerProtocol { /// resulting signals (into a producer of values), according to the /// semantics of the given strategy. /// - /// If `self` emits an error, the returned producer will forward that - /// error immediately. + /// - warning: If `self` emits an error, the returned producer will forward + /// that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> SignalProducer { return map(transform).flatten(strategy) } @@ -867,8 +1016,13 @@ extension SignalProducerProtocol { /// resulting properties (into a producer of values), according to the /// semantics of the given strategy. /// - /// If `self` emits an error, the returned producer will forward that - /// error immediately. + /// - warning: If `self` emits an error, the returned producer will forward + /// that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a property with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> P) -> SignalProducer { return map(transform).flatten(strategy) } @@ -879,8 +1033,13 @@ extension SignalProducerProtocol where Error == NoError { /// resulting producers (into a producer of values), according to the /// semantics of the given strategy. /// - /// If any of the created producers fail, the returned producer will - /// forward that failure immediately. + /// - warning: If any of the created producers fail, the returned producer + /// will forward that failure immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> SignalProducer { return map(transform).flatten(strategy) } @@ -888,6 +1047,11 @@ extension SignalProducerProtocol where Error == NoError { /// Maps each event from `self` to a new producer, then flattens the /// resulting producers (into a producer of values), according to the /// semantics of the given strategy. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal producer with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> SignalProducer) -> SignalProducer { return map(transform).flatten(strategy) } @@ -896,8 +1060,13 @@ extension SignalProducerProtocol where Error == NoError { /// resulting signals (into a producer of values), according to the /// semantics of the given strategy. /// - /// If any of the created signals emit an error, the returned - /// producer will forward that error immediately. + /// - warning: If any of the created signals emit an error, the returned + /// producer will forward that error immediately. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> SignalProducer { return map(transform).flatten(strategy) } @@ -905,6 +1074,11 @@ extension SignalProducerProtocol where Error == NoError { /// Maps each event from `self` to a new producer, then flattens the /// resulting signals (into a producer of values), according to the /// semantics of the given strategy. + /// + /// - parameters: + /// - strategy: Strategy used when flattening signals. + /// - transform: A closure that takes a value emitted by `self` and + /// returns a signal with transformed value. public func flatMap(_ strategy: FlattenStrategy, transform: @escaping (Value) -> Signal) -> SignalProducer { return map(transform).flatten(strategy) } @@ -914,6 +1088,10 @@ extension SignalProducerProtocol where Error == NoError { extension SignalProtocol { /// Catches any failure that may occur on the input signal, mapping to a new /// producer that starts in its place. + /// + /// - parameters: + /// - handler: A closure that accepts emitted error and returns a signal + /// producer with a different type of error. public func flatMapError(_ handler: @escaping (Error) -> SignalProducer) -> Signal { return Signal { observer in self.observeFlatMapError(handler, observer, SerialDisposable()) @@ -942,6 +1120,10 @@ extension SignalProtocol { extension SignalProducerProtocol { /// Catches any failure that may occur on the input producer, mapping to a /// new producer that starts in its place. + /// + /// - parameters: + /// - handler: A closure that accepts emitted error and returns a signal + /// producer with a different type of error. public func flatMapError(_ handler: @escaping (Error) -> SignalProducer) -> SignalProducer { return SignalProducer { observer, disposable in let serialDisposable = SerialDisposable() diff --git a/Sources/Lifetime.swift b/Sources/Lifetime.swift index 7a8e3c203..fe05dc6a6 100644 --- a/Sources/Lifetime.swift +++ b/Sources/Lifetime.swift @@ -4,9 +4,11 @@ import enum Result.NoError /// Represents the lifetime of an object, and provides a hook to observe when /// the object deinitializes. public final class Lifetime { - /// MARK: Type properties and methods + // MARK: Type properties and methods /// Factory method for creating a `Lifetime` and its associated `Token`. + /// + /// - returns: A `(lifetime, token)` tuple. public static func make() -> (lifetime: Lifetime, token: Token) { let token = Token() return (Lifetime(token), token) @@ -17,7 +19,7 @@ public final class Lifetime { return Lifetime(ended: .empty) } - /// MARK: Instance properties + // MARK: Instance properties /// A signal that sends a `completed` event when the lifetime ends. /// @@ -25,7 +27,7 @@ public final class Lifetime { /// is to be attached. public let ended: Signal<(), NoError> - /// MARK: Initializers + // MARK: Initializers /// Initialize a `Lifetime` object with the supplied ended signal. /// diff --git a/Sources/Property.swift b/Sources/Property.swift index 11ecf197b..49dfa6ab3 100644 --- a/Sources/Property.swift +++ b/Sources/Property.swift @@ -31,6 +31,12 @@ public protocol PropertyProtocol: class, BindingSource { } extension PropertyProtocol { + /// Observe the property by sending all of future value changes to the + /// given `observer` during the given `lifetime`. + /// + /// - parameters: + /// - observer: An observer to send the events to. + /// - lifetime: A lifetime of the observing object. @discardableResult public func observe(_ observer: Observer, during lifetime: Lifetime) -> Disposable? { return producer.observe(observer, during: lifetime) diff --git a/Sources/Reactive.swift b/Sources/Reactive.swift index a1412aa16..e48c02b4f 100644 --- a/Sources/Reactive.swift +++ b/Sources/Reactive.swift @@ -23,10 +23,10 @@ public struct Reactive { /// The `Base` instance the extensions would be invoked with. public let base: Base - // Construct a proxy. - // - // - parameters: - // - base: The object to be proxied. + /// Construct a proxy + /// + /// - parameters: + /// - base: The object to be proxied. fileprivate init(_ base: Base) { self.base = base } diff --git a/Sources/Scheduler.swift b/Sources/Scheduler.swift index 198fc4806..ebee7c08c 100644 --- a/Sources/Scheduler.swift +++ b/Sources/Scheduler.swift @@ -299,6 +299,9 @@ public final class QueueScheduler: DateScheduler { /// Schedules a recurring action at the given interval with provided leeway, /// beginning at the given start time. /// + /// - precondition: `interval` must be non-negative number. + /// - precondition: `leeway` must be non-negative number. + /// /// - parameters: /// - date: A date to schedule the first action for. /// - interval: A repetition interval. @@ -427,6 +430,8 @@ public final class TestScheduler: DateScheduler { /// Schedules a recurring action at the given interval, beginning at the /// given start date. /// + /// - precondition: `interval` must be non-negative. + /// /// - parameters: /// - date: A date to schedule the first action for. /// - interval: A repetition interval. diff --git a/Sources/Signal.swift b/Sources/Signal.swift index dc4ae0020..1560d7784 100644 --- a/Sources/Signal.swift +++ b/Sources/Signal.swift @@ -974,6 +974,8 @@ extension SignalProtocol { /// - note: failed and `interrupted` events are always scheduled /// immediately. /// + /// - precondition: `interval` must be non-negative number. + /// /// - parameters: /// - interval: Interval to delay `value` and `completed` events by. /// - scheduler: A scheduler to deliver delayed events on. @@ -1003,6 +1005,8 @@ extension SignalProtocol { /// Skip first `count` number of values then act as usual. /// + /// - precondition: `count` must be non-negative number. + /// /// - parameters: /// - count: A number of values to skip. /// @@ -1739,6 +1743,8 @@ extension SignalProtocol { /// a value is being throttled, and if there is a new value sent, /// the new value will be passed anyway. /// + /// - precondition: `interval` must be non-negative number. + /// /// - parameters: /// - interval: Number of seconds to wait between sent values. /// - scheduler: A scheduler to deliver events on. @@ -1913,6 +1919,8 @@ extension SignalProtocol { /// that value will be discarded and the returned signal will /// terminate immediately. /// + /// - precondition: `interval` must be non-negative number. + /// /// - parameters: /// - interval: A number of seconds to wait before sending a value. /// - scheduler: A scheduler to send values on. @@ -2193,6 +2201,8 @@ extension SignalProtocol { /// The signal must complete synchronously (or on a faster /// scheduler) to avoid the timeout. /// + /// - precondition: `interval` must be non-negative number. + /// /// - parameters: /// - error: Error to send with failed event if `self` is not completed /// when `interval` passes. diff --git a/Sources/SignalProducer.swift b/Sources/SignalProducer.swift index 351abc539..9389f5666 100644 --- a/Sources/SignalProducer.swift +++ b/Sources/SignalProducer.swift @@ -536,7 +536,7 @@ extension SignalProducerProtocol { /// Yield an array of values until it reaches a certain count. /// - /// - precondition: `count` should be greater than zero. + /// - precondition: `count` must be greater than zero. /// /// - note: When the count is reached the array is sent and the signal /// starts over yielding a new array of values. @@ -1682,6 +1682,8 @@ extension SignalProducerProtocol { /// - note: Repeating `0` times results in a producer that instantly /// completes. /// + /// - precondition: `count` must be non-negative integer. + /// /// - parameters: /// - count: Number of repetitions. /// @@ -2137,7 +2139,7 @@ private struct ReplayState { /// - note: This timer will never complete naturally, so all invocations of /// `start()` must be disposed to avoid leaks. /// -/// - precondition: Interval must be non-negative number. +/// - precondition: `interval` must be non-negative number. /// /// - note: If you plan to specify an `interval` value greater than 200,000 /// seconds, use `timer(interval:on:leeway:)` instead @@ -2160,9 +2162,9 @@ public func timer(interval: DispatchTimeInterval, on scheduler: DateScheduler) - /// - note: This timer will never complete naturally, so all invocations of /// `start()` must be disposed to avoid leaks. /// -/// - precondition: Interval must be non-negative number. +/// - precondition: `interval` must be non-negative number. /// -/// - precondition: Leeway must be non-negative number. +/// - precondition: `leeway` must be non-negative number. /// /// - parameters: /// - interval: An interval between invocations.