PR Feedback: Require main thread for all edit commands, various cleanup.

AsyncDisplayKit/ASTableView.h

@@ -94,7 +94,7 @@
 - (void)reloadData;
 
 /**
- *  begins a batch of insert, delete reload and move operations. Batches are asynchronous an thread safe.
+ *  begins a batch of insert, delete reload and move operations. This method must be called from the main thread.
  */
 - (void)beginUpdates;
 
@@ -102,7 +102,7 @@
  *  Concludes a series of method calls that insert, delete, select, or reload rows and sections of the table view.
  *  You call this method to bracket a series of method calls that begins with beginUpdates and that consists of operations
  *  to insert, delete, select, and reload rows and sections of the table view. When you call endUpdates, ASTableView begins animating
- *  the operations simultaneously. This method is asynchronous and thread safe. It's important to remeber that the ASTableView will
+ *  the operations simultaneously. This method is must be called from the main thread. It's important to remeber that the ASTableView will
  *  be processing the updates asynchronously after this call is completed.
  *
  *  @param animated   NO to disable all animations.
@@ -116,7 +116,7 @@
  *  Concludes a series of method calls that insert, delete, select, or reload rows and sections of the table view.
  *  You call this method to bracket a series of method calls that begins with beginUpdates and that consists of operations 
  *  to insert, delete, select, and reload rows and sections of the table view. When you call endUpdates, ASTableView begins animating
- *  the operations simultaneously. This method is asynchronous and thread safe. It's important to remeber that the ASTableView will
+ *  the operations simultaneously. This method is must be called from the main thread. It's important to remeber that the ASTableView will
  *  be processing the updates asynchronously after this call and are not guaranteed to be reflected in the ASTableView until
  *  the completion block is executed.
  *
@@ -134,8 +134,7 @@
  * 
  * @param animation A constant that indicates how the insertion is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)insertSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation;
@@ -147,8 +146,7 @@
  *
  * @param animation A constant that indicates how the deletion is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)deleteSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation;
@@ -160,8 +158,7 @@
  *
  * @param animation A constant that indicates how the reloading is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)reloadSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation;
@@ -173,8 +170,7 @@
  *
  * @param newSection The index that is the destination of the move for the section.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection;
@@ -186,8 +182,7 @@
  *
  * @param animation A constant that indicates how the insertion is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)insertRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation;
@@ -199,8 +194,7 @@
  *
  * @param animation A constant that indicates how the deletion is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)deleteRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation;
@@ -212,8 +206,7 @@
  *
  * @param animation A constant that indicates how the reloading is to be animated. See UITableViewRowAnimation.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)reloadRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation;
@@ -225,8 +218,7 @@
  *
  * @param newIndexPath The index path that is the destination of the move for the row.
  *
- * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated)
- * and the UI table view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes
+ * @discussion This method must be called from the main thread. The asyncDataSource must be updated to reflect the changes
  * before this method is called.
  */
 - (void)moveRowAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath;
@@ -249,7 +241,8 @@
 
 /**
  * YES to automatically adjust the contentOffset when cells are inserted or deleted "before"
- * visible cells, maintaining the users' visible scroll position.
+ * visible cells, maintaining the users' visible scroll position. Currently this feature tracks insertions, moves and deletions of
+ * cells, but section edits are ignored.
  *
  * default is NO.
  */