Merge pull request #274 from eimantas/markup-updates

[WIP] Update documentation markup

Author: andersio

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<State: RawRepresentable>: AtomicStateProtocol
 	///
 	/// - parameters:
 	///   - expected: The expected state.
+	///   - next: The state to transition to.
 	///
 	/// - returns:
 	///   `true` if the transition succeeds. `false` otherwise.

Sources/Disposable.swift

@@ -112,7 +112,10 @@ public final class CompositeDisposable: Disposable {
 	private var state: UnsafeAtomicState<DisposableState>
 
 	/// 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<DisposableState>
 		private var bagToken: RemovalToken?

Sources/Flatten.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,15 +19,15 @@ 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.
 	///
 	/// - note: Consider using `Lifetime.observeEnded` if only a closure observer
 	///         is to be attached.
  	public let ended: Signal<(), NoError>
 
-	/// MARK: Initializers
+	// MARK: Initializers
 
 	/// Initialize a `Lifetime` object with the supplied ended signal.
 	///

Sources/Lifetime.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<Value, NoError>, during lifetime: Lifetime) -> Disposable? {
 		return producer.observe(observer, during: lifetime)

Sources/Property.swift

@@ -23,10 +23,10 @@ public struct Reactive<Base> {
 	/// 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
 	}

Sources/Reactive.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.

Sources/Scheduler.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.

Sources/Signal.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<Value, Error: Swift.Error> {
 /// - 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.