[collections] Docs and delete the mutable collection view model becau…

…se it's untested.

src/Nimbus.xcodeproj/project.pbxproj

@@ -5668,6 +5668,7 @@
 				66FC98541703F9D8004E8FB8 /* Release */,
 			);
 			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
 		};
 		C7BBC6FF16DDC0E700833DC9 /* Build configuration list for PBXNativeTarget "NimbusTextField" */ = {
 			isa = XCConfigurationList;

src/collections/src/NICollectionViewCellFactory.h

@@ -31,7 +31,7 @@
  *
  * This factory is designed to be used with NICollectionViewModel, though one could easily use
  * it with other collection view data source implementations simply by providing nil for the
- * collection view model.
+ * collection view model argument.
  *
  * If you instantiate an NICollectionViewCellFactory then you can provide explicit mappings from
  * objects to cells. This is helpful if the effort required to implement the NICollectionViewCell
@@ -43,8 +43,8 @@
 @interface NICollectionViewCellFactory : NSObject <NICollectionViewModelDelegate>
 
 /**
- * Creates a cell from a given object if and only if the object conforms to the NICollectionViewCellObject
- * protocol.
+ * Creates a cell from a given object if and only if the object conforms to the
+ * NICollectionViewCellObject protocol.
  *
  * This method signature matches the NICollectionViewModelDelegate method so that you can
  * set this factory as the model's delegate:
@@ -60,13 +60,13 @@ _model.delegate = (id)[NICollectionViewCellFactory class];
  *
  * @code
 - (UICollectionViewCell *)collectionViewModel:(NICollectionViewModel *)collectionViewModel
-                   cellForCollectionView:(UICollectionView *)collectionView
-                        atIndexPath:(NSIndexPath *)indexPath
-                         withObject:(id)object {
+                        cellForCollectionView:(UICollectionView *)collectionView
+                                  atIndexPath:(NSIndexPath *)indexPath
+                                   withObject:(id)object {
   UICollectionViewCell* cell = [NICollectionViewCellFactory collectionViewModel:collectionViewModel
-                                       cellForCollectionView:collectionView
-                                            atIndexPath:indexPath
-                                             withObject:object];
+                                                          cellForCollectionView:collectionView
+                                                                    atIndexPath:indexPath
+                                                                     withObject:object];
   if (nil == cell) {
     // Custom cell creation here.
   }
@@ -85,8 +85,24 @@ _model.delegate = (id)[NICollectionViewCellFactory class];
  */
 - (void)mapObjectClass:(Class)objectClass toCellClass:(Class)collectionViewCellClass;
 
+/**
+ * Returns the mapped cell class for an object at a given index path.
+ *
+ * Explicitly mapped classes in the receiver take precedence over implicitly mapped classes.
+ *
+ * This method is helpful when implementing layout calculation methods for your collection view. You
+ * can fetch the cell class and then perform any selectors that are necessary for calculating the
+ * dimensions of the cell before it is instantiated.
+ */
 - (Class)collectionViewCellClassForItemAtIndexPath:(NSIndexPath *)indexPath model:(NICollectionViewModel *)model;
 
+/**
+ * Returns the mapped cell class for an object at a given index path.
+ *
+ * This method is helpful when implementing layout calculation methods for your collection view. You
+ * can fetch the cell class and then perform any selectors that are necessary for calculating the
+ * dimensions of the cell before it is instantiated.
+ */
 + (Class)collectionViewCellClassForItemAtIndexPath:(NSIndexPath *)indexPath model:(NICollectionViewModel *)model;
 
 @end
@@ -112,10 +128,11 @@ _model.delegate = (id)[NICollectionViewCellFactory class];
 /**
  * The protocol for an object that can be used in the NICollectionViewCellFactory.
  *
- *      @ingroup TableCellFactory
+ *      @ingroup CollectionViewCellFactory
  */
 @protocol NICollectionViewCellObject <NSObject>
 @required
+
 /** The class of cell to be created when this object is passed to the cell factory. */
 - (Class)collectionViewCellClass;
 
@@ -124,16 +141,17 @@ _model.delegate = (id)[NICollectionViewCellFactory class];
 /**
  * The protocol for a cell created in the NICollectionViewCellFactory.
  *
- * Cells that implement this protocol are given the object that implemented the NICollectionViewCellObject
- * protocol and returned this cell's class name in @link NICollectionViewCellObject::collectionViewCellClass collectionViewCellClass@endlink.
+ * Cells that implement this protocol are given the object that implemented the
+ * NICollectionViewCellObject protocol and returned this cell's class name in
+ * @link NICollectionViewCellObject::collectionViewCellClass collectionViewCellClass@endlink.
  *
- *      @ingroup TableCellFactory
+ *      @ingroup CollectionViewCellFactory
  */
 @protocol NICollectionViewCell <NSObject>
 @required
 
 /**
- * Called when a cell is created and reused.
+ * Called both when a cell is created and when it is reused.
  *
  * Implement this method to customize the cell's properties for display using the given object.
  */
@@ -152,7 +170,7 @@ _model.delegate = (id)[NICollectionViewCellFactory class];
  * to the cell view, you can create an NICollectionViewCellObject and pass the class name of the cell.
  *
 @code
-[tableContents addObject:[NICollectionViewCellObject objectWithCellClass:[LoadMoreCell class]]];
+[contents addObject:[NICollectionViewCellObject objectWithCellClass:[LoadMoreCell class]]];
 @endcode
  */
 @interface NICollectionViewCellObject : NSObject <NICollectionViewCellObject>

src/collections/src/NICollectionViewModel+Private.h

@@ -25,7 +25,6 @@
 - (void)_resetCompiledData;
 - (void)_compileDataWithListArray:(NSArray *)listArray;
 - (void)_compileDataWithSectionedArray:(NSArray *)sectionedArray;
-- (void)_compileSectionIndex;
 
 @end
 

src/collections/src/NICollectionViewModel.h

@@ -27,26 +27,23 @@
 // Classes used when creating NICollectionViewModels.
 @class NICollectionViewModelFooter;  // Provides the information for a footer.
 
-typedef enum {
-  NICollectionViewModelSectionIndexNone, // Displays no section index.
-  NICollectionViewModelSectionIndexDynamic, // Generates a section index from the first letters of the section titles.
-  NICollectionViewModelSectionIndexAlphabetical, // Generates an alphabetical section index.
-} NICollectionViewModelSectionIndex;
-
 /**
- * A non-mutable table view model that complies to the UITableViewDataSource protocol.
+ * A non-mutable collection view model that complies to the UICollectionViewDataSource protocol.
  *
- * This model allows you to easily create a data source for a UITableView without having to
- * implement the UITableViewDataSource methods in your UITableViewController.
+ * This model allows you to easily create a data source for a UICollectionView without having to
+ * implement the UICollectionViewDataSource methods in your controller.
  *
  * This base class is non-mutable, much like an NSArray. You must initialize this model with
  * the contents when you create it.
  *
- *      @ingroup TableViewModels
+ * This model simply manages the data relationship with your collection view. It is up to you to
+ * implement the collection view's layout object.
+ *
+ *      @ingroup CollectionViewModels
  */
 @interface NICollectionViewModel : NSObject <UICollectionViewDataSource>
 
-#pragma mark Creating Table View Models
+#pragma mark Creating Collection View Models
 
 // Designated initializer.
 - (id)initWithDelegate:(id<NICollectionViewModelDelegate>)delegate;
@@ -58,32 +55,22 @@ typedef enum {
 
 - (id)objectAtIndexPath:(NSIndexPath *)indexPath;
 
-#pragma mark Configuration
-
-// Immediately compiles the section index.
-- (void)setSectionIndexType:(NICollectionViewModelSectionIndex)sectionIndexType showsSearch:(BOOL)showsSearch showsSummary:(BOOL)showsSummary;
-
-@property (nonatomic, readonly, assign) NICollectionViewModelSectionIndex sectionIndexType; // Default: NICollectionViewModelSectionIndexNone
-@property (nonatomic, readonly, assign) BOOL sectionIndexShowsSearch; // Default: NO
-@property (nonatomic, readonly, assign) BOOL sectionIndexShowsSummary; // Default: NO
-
-#pragma mark Creating Table View Cells
+#pragma mark Creating Collection View Cells
 
 @property (nonatomic, NI_WEAK) id<NICollectionViewModelDelegate> delegate;
 
 @end
 
 /**
- * A protocol for NICollectionViewModel to fetch rows to be displayed for the table view.
+ * A protocol for NICollectionViewModel to fetch rows to be displayed for the collection view.
  *
- *      @ingroup TableViewModels
+ *      @ingroup CollectionViewModels
  */
 @protocol NICollectionViewModelDelegate <NSObject>
-
 @required
 
 /**
- * Fetches a table view cell at a given index path with a given object.
+ * Fetches a collection view cell at a given index path with a given object.
  *
  * The implementation of this method will generally use object to customize the cell.
  */
@@ -114,7 +101,7 @@ typedef enum {
 
 @end
 
-/** @name Creating Table View Models */
+/** @name Creating Collection View Models */
 
 /**
  * Initializes a newly allocated static model with the given delegate and empty contents.
@@ -139,7 +126,7 @@ typedef enum {
  *  [NSDictionary dictionaryWithObject:@"Row 2" forKey:@"title"],
  *  [NSDictionary dictionaryWithObject:@"Row 3" forKey:@"title"],
  *  nil];
- * [[NIStaticTableViewModel alloc] initWithListArray:contents delegate:self];
+ * [[NICollectionViewModel alloc] initWithListArray:contents delegate:self];
  * @endcode
  *
  *      @fn NICollectionViewModel::initWithListArray:delegate:
@@ -166,7 +153,7 @@ typedef enum {
  *  [NSDictionary dictionaryWithObject:@"Row 3" forKey:@"title"],
  *  [NICollectionViewModelFooter footerWithTitle:@"Footer"],
  *  nil];
- * [[NIStaticTableViewModel alloc] initWithSectionedArray:contents delegate:self];
+ * [[NICollectionViewModel alloc] initWithSectionedArray:contents delegate:self];
  * @endcode
  *
  *      @fn NICollectionViewModel::initWithSectionedArray:delegate:
@@ -185,60 +172,10 @@ typedef enum {
  */
 
 
-/** @name Configuration */
-
-/**
- * Configures the model's section index properties.
- *
- * Calling this method will compile the section index depending on the index type chosen.
- *
- *      @param sectionIndexType The type of section index to display.
- *      @param showsSearch      Whether or not to show the search icon at the top of the index.
- *      @param showsSummary     Whether or not to show the summary icon at the bottom of the index.
- *      @fn NICollectionViewModel::setSectionIndexType:showsSearch:showsSummary:
- */
-
-/**
- * The section index type.
- *
- * You will likely use NICollectionViewModelSectionIndexAlphabetical in practice.
- *
- * NICollectionViewModelSectionIndexNone by default.
- *
- *      @fn NICollectionViewModel::sectionIndexType
- */
+/** @name Creating Collection View Cells */
 
 /**
- * Whether or not the search symbol will be shown in the section index.
- *
- * NO by default.
- *
- *      @fn NICollectionViewModel::sectionIndexShowsSearch
- */
-
-/**
- * Whether or not the summary symbol will be shown in the section index.
- *
- * NO by default.
- *
- *      @fn NICollectionViewModel::sectionIndexShowsSummary
- */
-
-
-/** @name Creating Table View Cells */
-
-/**
- * A delegate used to fetch table view cells for the data source.
+ * A delegate used to fetch collection view cells for the data source.
  *
  *      @fn NICollectionViewModel::delegate
  */
-
-#if NS_BLOCKS_AVAILABLE
-
-/**
- * A block used to create a UICollectionViewCell for a given object.
- *
- *      @fn NICollectionViewModel::createCellBlock
- */
-
-#endif // #if NS_BLOCKS_AVAILABLE