Add doc comments to reduce operator

Sources/FBLPromises/include/FBLPromise+Reduce.h

@@ -23,9 +23,32 @@ NS_ASSUME_NONNULL_BEGIN
 typedef id __nullable (^FBLPromiseReducerBlock)(Value __nullable partial, id next)
     NS_SWIFT_UNAVAILABLE("");
 
+/**
+ Sequentially reduces a collection of values to a single promise using a given combining block
+ and the value `self` resolves with as initial value.
+
+ @param items An array of values to process in order.
+ @param reducer A block to combine an accumulating value and an element of the sequence into
+                the new accumulating value or a promise resolved with it, to be used in the next
+                call of the `reducer` or returned to the caller.
+ @return A new pending promise returned from the last `reducer` invocation.
+         Or `self` if `items` is empty.
+ */
 - (FBLPromise *)reduce:(NSArray *)items
                combine:(FBLPromiseReducerBlock)reducer NS_SWIFT_UNAVAILABLE("");
 
+/**
+ Sequentially reduces a collection of values to a single promise using a given combining block
+ and the value `self` resolves with as initial value.
+
+ @param queue A queue to dispatch on.
+ @param items An array of values to process in order.
+ @param reducer A block to combine an accumulating value and an element of the sequence into
+                the new accumulating value or a promise resolved with it, to be used in the next
+                call of the `reducer` or returned to the caller.
+ @return A new pending promise returned from the last `reducer` invocation.
+         Or `self` if `items` is empty.
+ */
 - (FBLPromise *)onQueue:(dispatch_queue_t)queue
                  reduce:(NSArray *)items
                 combine:(FBLPromiseReducerBlock)reducer NS_SWIFT_UNAVAILABLE("");

Sources/Promises/Promise+Reduce.swift

@@ -15,21 +15,42 @@
 import Dispatch
 
 public extension Promise {
+  public typealias Reducer<Element> = (Value, Element) throws -> Promise<Value>
 
+  /// Sequentially reduces a collection of values to a single promise using a given combining block
+  /// and the value `self` resolves with as initial value.
+  /// - parameters:
+  ///   - queue: A queue to execute `reducer` block on.
+  ///   - items: A sequence of values to process in order.
+  ///   - reducer: A block to combine an accumulating value and an element of the sequence into
+  ///              a promise resolved with the new accumulating value, to be used in the next call
+  ///              of the `reducer` or returned to the caller.
+  /// - returns: A new pending promise returned from the last `reducer` invocation.
+  ///            Or `self` if `items` is empty.
   @discardableResult
   public func reduce<Element>(
     on queue: DispatchQueue = .promises,
     _ items: Element...,
-    combine reducer: @escaping (Value, Element) throws -> Promise<Value>
+    combine reducer: @escaping Reducer<Element>
   ) -> Promise<Value> {
     return reduce(on: queue, items, reducer)
   }
 
+  /// Sequentially reduces a collection of values to a single promise using a given combining block
+  /// and the value `self` resolves with as initial value.
+  /// - parameters:
+  ///   - queue: A queue to execute `reducer` block on.
+  ///   - items: A sequence of values to process in order.
+  ///   - reducer: A block to combine an accumulating value and an element of the sequence into
+  ///              a promise resolved with the new accumulating value, to be used in the next call
+  ///              of the `reducer` or returned to the caller.
+  /// - returns: A new pending promise returned from the last `reducer` invocation.
+  ///            Or `self` if `items` is empty.
   @discardableResult
   public func reduce<Container: Sequence>(
     on queue: DispatchQueue = .promises,
     _ items: Container,
-    _ reducer: @escaping (Value, Container.Element) throws -> Promise<Value>
+    _ reducer: @escaping Reducer<Container.Element>
   ) -> Promise<Value> {
     return items.reduce(self) { promise, item in
       promise.then { value in

Tests/PromisesTests/Promise+ReduceTests.swift

@@ -17,15 +17,6 @@ import XCTest
 @testable import Promises
 
 class PromiseReduceTests: XCTestCase {
-  func test() {
-    Promise("").reduce(1, 2, 3) { partialString, nextNumber in
-      return Promise(partialString + String(nextNumber))
-    }.then { string in
-      print(string)
-    }
-    XCTAssert(waitForPromises(timeout: 10))
-  }
-
   func testPromiseReduce() {
     // Arrange.
     let numbers = [1, 2, 3]
@@ -34,7 +25,11 @@ class PromiseReduceTests: XCTestCase {
     // Act.
     Promise("").reduce(numbers) { partialString, nextNumber in
       count += 1
-      return Promise(partialString + String(nextNumber))
+      return Promise { fulfill, _ in
+        Test.delay(0.1) {
+          fulfill(partialString + String(nextNumber))
+        }
+      }
     }.then { string in
       XCTAssertEqual(string, numbers.map(String.init).reduce("", +))
       count += 1