[ASDataController] Call All Completion Handlers after Nested Batch Updates (#2274)

* Add tests for batch update completion handler calling

* Ensure we call all completion handlers after collection view updates

* Tweak it

* Fix the doc

* Minor improvements

* Document addCompletionHandler better

AsyncDisplayKitTests/ASCollectionViewTests.mm

@@ -473,4 +473,49 @@
   [[UIDevice currentDevice] setValue:@(oldDeviceOrientation) forKey:@"orientation"];
 }
 
+/**
+ * See corresponding test in ASUICollectionViewTests
+ *
+ * @discussion Currently, we do not replicate UICollectionView's call order (outer, inner0, inner1, ...)
+ *   and instead call (inner0, inner1, outer, ...). This is because we primarily provide a
+ *   beginUpdates/endUpdatesWithCompletion: interface (like UITableView). With UICollectionView's
+ *   performBatchUpdates:completion:, the completion block is enqueued at -beginUpdates time.
+ *   With our tableView-like scheme, the completion block is provided at -endUpdates time
+ *   and it is naturally enqueued at this time. It is assumed that this is an acceptable deviation,
+ *   and that developers do not expect a particular completion order guarantee.
+ */
+- (void)testThatNestedBatchCompletionsAreCalledInOrder
+{
+  ASCollectionViewTestController *testController = [[ASCollectionViewTestController alloc] initWithNibName:nil bundle:nil];
+
+  ASCollectionView *cv = testController.collectionView;
+
+  XCTestExpectation *inner0 = [self expectationWithDescription:@"Inner completion 0 is called"];
+  XCTestExpectation *inner1 = [self expectationWithDescription:@"Inner completion 1 is called"];
+  XCTestExpectation *outer = [self expectationWithDescription:@"Outer completion is called"];
+
+  NSMutableArray<XCTestExpectation *> *completions = [NSMutableArray array];
+
+  [cv performBatchUpdates:^{
+    [cv performBatchUpdates:^{
+
+    } completion:^(BOOL finished) {
+      [completions addObject:inner0];
+      [inner0 fulfill];
+    }];
+    [cv performBatchUpdates:^{
+
+    } completion:^(BOOL finished) {
+      [completions addObject:inner1];
+      [inner1 fulfill];
+    }];
+  } completion:^(BOOL finished) {
+    [completions addObject:outer];
+    [outer fulfill];
+  }];
+
+  [self waitForExpectationsWithTimeout:5 handler:nil];
+  XCTAssertEqualObjects(completions, (@[ inner0, inner1, outer ]), @"Expected completion order to be correct");
+}
+
 @end