Docs updates and refinements, #181

Summary:
Did a full pass on documentation.

- Clean up
- Fixes
- Better markdown

> **NOTE:** this PR does not re-gen docs. I will do that next. Before we cut 2.0
Closes #198

Reviewed By: rnystrom

Differential Revision: D4181253

Pulled By: jessesquires

fbshipit-source-id: 133c4af392bb396ecc6eff0c895c55e6d18730b7

Source/IGListAdapter.h

@@ -23,14 +23,19 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A block to execute when list updates completes.
+
+ @param finished Specifies whether or not the updates finished.
+ */
 typedef void (^IGListUpdaterCompletion)(BOOL finished);
 
 /**
- IGListAdapter objects provide an abstraction for feeds of objects in a UICollectionView by breaking each object into
- individual sections, called "section controllers". These controllers (objects conforming to IGListSectionType) act as a
+ `IGListAdapter` objects provide an abstraction for feeds of objects in a `UICollectionView` by breaking each object into
+ individual sections, called "section controllers". These controllers (objects conforming to `IGListSectionType`) act as a
  data source and delegate for each section.
 
- Feed implementations must act as the data source for an IGListAdapter in order to drive the objects and section
+ Feed implementations must act as the data source for an `IGListAdapter` in order to drive the objects and section
  controllers in a collection view.
  */
 IGLK_SUBCLASSING_RESTRICTED
@@ -57,14 +62,14 @@ IGLK_SUBCLASSING_RESTRICTED
 @property (nonatomic, nullable, weak) id <IGListAdapterDelegate> delegate;
 
 /**
- The object that receives UICollectionViewDelegate events.
+ The object that receives `UICollectionViewDelegate` events.
 
- @note This object /will not/ receive UIScrollViewDelegate events. Instead use scrollViewDelegate.
+ @note This object *will not* receive `UIScrollViewDelegate` events. Instead use scrollViewDelegate.
  */
 @property (nonatomic, nullable, weak) id <UICollectionViewDelegate> collectionViewDelegate;
 
 /**
- The object that receives UIScrollViewDelegate events.
+ The object that receives `UIScrollViewDelegate` events.
  */
 @property (nonatomic, nullable, weak) id <UIScrollViewDelegate> scrollViewDelegate;
 
@@ -74,43 +79,43 @@ IGLK_SUBCLASSING_RESTRICTED
 @property (nonatomic, assign) IGListExperiment experiments;
 
 /**
- Initialize a new IGListAdapter object with a collection view, data source, and updating delegate.
+ Initializes a new `IGListAdapter` object.
 
- @param updatingDelegate An object that manages updates to the UICollectionView.
+ @param updatingDelegate An object that manages updates to the collection view.
  @param viewController   The view controller that will house the adapter.
  @param workingRangeSize The number of objects before and after the viewport to consider within the working range.
 
- @return A new IGListAdapter object.
+ @return A new list adapter object.
 
  @note The working range is the number of objects beyond the visible objects (plus and minus) that should be
  notified when they are close to being visible. For instance, if you have 3 objects on screen and a working range of 2,
  the previous and succeeding 2 objects will be notified that they are within the working range. As you scroll the list
  the range is updated as objects enter and exit the working range.
 
- To opt out of using the working range, you can provide a value of 0.
+ To opt out of using the working range, you can provide a value of `0`.
  */
 - (instancetype)initWithUpdater:(id <IGListUpdatingDelegate>)updatingDelegate
                  viewController:(nullable UIViewController *)viewController
                workingRangeSize:(NSUInteger)workingRangeSize NS_DESIGNATED_INITIALIZER;
 
 /**
  Perform an update from the previous state of the data source. This is analagous to calling
- -[UICollectionView performBatchUpdates:completion:].
+ `-[UICollectionView performBatchUpdates:completion:]`.
 
  @param animated   A flag indicating if the transition should be animated.
- @param completion A block executed when the update completes.
+ @param completion The block to execute when the update completes.
  */
 - (void)performUpdatesAnimated:(BOOL)animated completion:(nullable IGListUpdaterCompletion)completion;
 
 /**
  Perform an immediate reload of the data in the data source, discarding the old objects.
 
- @param completion A block executed when the reload completes.
+ @param completion The block to execute when the reload completes.
  */
 - (void)reloadDataWithCompletion:(nullable IGListUpdaterCompletion)completion;
 
 /**
- Reload the infra for specific objects only.
+ Reload the list for only the specified objects.
 
  @param objects The objects to reload.
  */
@@ -121,41 +126,41 @@ IGLK_SUBCLASSING_RESTRICTED
 
  @param sectionController A list object.
 
- @return The section index of the list or NSNotFound.
+ @return The section index of the list if it exists, otherwise `NSNotFound`.
  */
 - (NSUInteger)sectionForSectionController:(IGListSectionController <IGListSectionType> *)sectionController;
 
 /**
- Fetch an section controller for an object in the feed. Constant time lookup.
+ Returns the section controller for the specified object. Constant time lookup.
 
  @param object An object from the data source.
 
- @return An section controller or nil.
+ @return An section controller or `nil` if `object` is not in the list.
 
- @see -[IGListAdapterDataSource listAdapter:sectionControllerForObject:]
+ @see `-[IGListAdapterDataSource listAdapter:sectionControllerForObject:]`
  */
 - (__kindof IGListSectionController <IGListSectionType> * _Nullable)sectionControllerForObject:(id)object;
 
 /**
- Fetch the object corresponding to a section in the feed. Constant time lookup.
+ Returns the object corresponding to a section in the list. Constant time lookup.
 
- @param section A section in the feed.
+ @param section A section in the list.
 
- @return An object or nil.
+ @return The object for the specified section, or `nil` if the section does not exist.
  */
 - (nullable id)objectAtSection:(NSUInteger)section;
 
 /**
- Fetch the section corresponding to an object in the feed. Constant time lookup.
+ Returns the section corresponding to the specified object in the list. Constant time lookup.
 
- @param object An object in the feed
+ @param object An object in the list.
 
- @return A section index if found or NSNotFound.
+ @return The section index of `object` if found, otherwise `NSNotFound`.
  */
 - (NSUInteger)sectionForObject:(id)object;
 
 /**
- A copy of all the objects currently powering the adapter.
+ Returns a copy of all the objects currently powering the adapter.
 
  @return An array of objects.
  */
@@ -176,9 +181,9 @@ IGLK_SUBCLASSING_RESTRICTED
 - (NSArray *)visibleObjects;
 
 /**
- Scroll to an object in the list adapter.
+ Scrolls to the sepcified object in the list adapter.
 
- @param object             The object to scroll to.
+ @param object             The object to which to scroll.
  @param supplementaryKinds The types of supplementary views in the section.
  @param scrollDirection    A flag indicating the direction to scroll.
  @param animated           A flag indicating if the transition should be animated.
@@ -189,7 +194,7 @@ IGLK_SUBCLASSING_RESTRICTED
               animated:(BOOL)animated;
 
 /**
- Query the size of a cell at the specified index path.
+ Returns the size of a cell at the specified index path.
 
  @param indexPath The index path of the cell.
 
@@ -198,7 +203,7 @@ IGLK_SUBCLASSING_RESTRICTED
 - (CGSize)sizeForItemAtIndexPath:(NSIndexPath *)indexPath;
 
 /**
- Query the size of a supplementary view in the list at the specified index path.
+ Returns the size of a supplementary view in the list at the specified index path.
 
  @param elementKind The kind of supplementary view.
  @param indexPath   The index path of the supplementary view.
@@ -208,7 +213,14 @@ IGLK_SUBCLASSING_RESTRICTED
 - (CGSize)sizeForSupplementaryViewOfKind:(NSString *)elementKind
                              atIndexPath:(NSIndexPath *)indexPath;
 
+/**
+ :nodoc:
+ */
 - (instancetype)init NS_UNAVAILABLE;
+
+/**
+ :nodoc:
+ */
 + (instancetype)new NS_UNAVAILABLE;
 
 @end

Source/IGListAdapterDataSource.h

@@ -19,45 +19,45 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- Implement this protocol to provide data to power an IGListAdapter feed.
+ Implement this protocol to provide data to an `IGListAdapter`.
  */
 @protocol IGListAdapterDataSource <NSObject>
 
 /**
- Asks the data source for an array of objects for each list in your feed.
+ Asks the data source for the objects to display in the list.
 
  @param listAdapter The list adapter requesting this information.
 
- @return An array of objects for the feed.
+ @return An array of objects for the list.
  */
 - (NSArray<id <IGListDiffable>> *)objectsForListAdapter:(IGListAdapter *)listAdapter;
 
 /**
- Asks the data source for a section controller for the specified data object.
+ Asks the data source for a section controller for the specified object in the list.
 
  @param listAdapter The list adapter requesting this information.
- @param object      An object in the feed, provided in -objectsForListAdapter:.
+ @param object      An object in the list.
 
- @return An IGListSectionType conforming object that can be displayed in the feed.
+ @return A new section controller instance that can be displayed in the list.
 
  @note New section controllers should be initialized here for objects when asked. You may pass any other data to
  the section controller at this time.
 
- Section controllers are initialized for all objects whenever the IGListAdapter is created, updated, or reloaded.
- Section controllers are reused when objects are moved or updated. Maintaining the -[IGListDiffable diffIdentifier]
- gauruntees this.
+ Section controllers are initialized for all objects whenever the `IGListAdapter` is created, updated, or reloaded.
+ Section controllers are reused when objects are moved or updated. Maintaining the `-[IGListDiffable diffIdentifier]`
+ guarentees this.
  */
 - (IGListSectionController <IGListSectionType> *)listAdapter:(IGListAdapter *)listAdapter sectionControllerForObject:(id)object;
 
 /**
- Asks the data source for a view to use as the collection view background when there are no objects.
+ Asks the data source for a view to use as the collection view background when the list is empty.
 
  @param listAdapter The list adapter requesting this information.
 
- @return A view to use as the collection view background, or nil if you don't want a background view.
+ @return A view to use as the collection view background, or `nil` if you don't want a background view.
 
  @note This method is called every time the list adapter is updated. You are free to return new views every time,
- but for performance reasons you may want to retain your own view and return it here. The infra is only responsible for
+ but for performance reasons you may want to retain the view and return it here. The infra is only responsible for
  adding the background view and maintaining its visibility.
  */
 - (nullable UIView *)emptyViewForListAdapter:(IGListAdapter *)listAdapter;

Source/IGListAdapterDelegate.h

@@ -14,7 +14,7 @@
 @protocol IGListAdapterDelegate <NSObject>
 
 /**
- Notifies the delegate that a list object is about to be displayed
+ Notifies the delegate that a list object is about to be displayed.
 
  @param listAdapter The list adapter sending this information.
  @param object      The object that will display.
@@ -23,11 +23,11 @@
 - (void)listAdapter:(IGListAdapter *)listAdapter willDisplayObject:(id)object atIndex:(NSInteger)index;
 
 /**
- Notifies the delegate that a list item is no longer being displayed
+ Notifies the delegate that a list object is no longer being displayed.
 
  @param listAdapter The list adapter sending this information.
  @param object      The object that ended display.
- @param index       The index of the item/object in the list.
+ @param index       The index of the object in the list.
  */
 - (void)listAdapter:(IGListAdapter *)listAdapter didEndDisplayingObject:(id)object atIndex:(NSInteger)index;
 

Source/IGListAdapterUpdater.h

@@ -17,22 +17,23 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- This is an out-of-box upater for IGListAdapters. It conforms to IGListUpdatingDelegate and does re-entrant, coalesced
- updating on a UICollectionView.
+ An `IGListAdapterUpdater` is a concrete type that conforms to `IGListUpdatingDelegate`.
+ It is an out-of-box upater for `IGListAdapter` objects to use.
 
- It also uses IGDiffKit (a least-minimal diff) for calculating UI updates when IGListAdapter calls
- -performUpdateWithCollectionView:fromObjects:toObjects:completion:.
+ @note This updater performs re-entrant, coalesced updating for a list. It also uses a least-minimal diff 
+ for calculating UI updates when `IGListAdapter` calls 
+ `-performUpdateWithCollectionView:fromObjects:toObjects:completion:`.
  */
 IGLK_SUBCLASSING_RESTRICTED
 @interface IGListAdapterUpdater : NSObject <IGListUpdatingDelegate>
 
 /**
- A delegate that receives events with data on the performance of a transition.
+ The delegate that receives events with data on the performance of a transition.
  */
 @property (nonatomic, weak) id<IGListAdapterUpdaterDelegate> delegate;
 
 /**
- A flag indicating if a move should be treated as a delete+insert.
+ A flag indicating if a move should be treated as a "delete, then insert" operation.
  */
 @property (nonatomic, assign) BOOL movesAsDeletesInserts;