diff --git a/Source/IGListAdapter.h b/Source/IGListAdapter.h index 331e15d2..236a4f6c 100644 --- a/Source/IGListAdapter.h +++ b/Source/IGListAdapter.h @@ -59,7 +59,7 @@ IGLK_SUBCLASSING_RESTRICTED /** The object that receives UICollectionViewDelegate events. - @discussion 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 collectionViewDelegate; @@ -82,7 +82,7 @@ IGLK_SUBCLASSING_RESTRICTED @return A new IGListAdapter object. - @discussion The working range is the number of objects beyond the visible objects (plus and minus) that should be + @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. diff --git a/Source/IGListAdapterDataSource.h b/Source/IGListAdapterDataSource.h index c28207bd..b7c5ea01 100644 --- a/Source/IGListAdapterDataSource.h +++ b/Source/IGListAdapterDataSource.h @@ -40,7 +40,7 @@ NS_ASSUME_NONNULL_BEGIN @return An IGListSectionType conforming object that can be displayed in the feed. - @discussion New section controllers should be initialized here for objects when asked. You may pass any other data to + @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. @@ -56,7 +56,7 @@ NS_ASSUME_NONNULL_BEGIN @return A view to use as the collection view background, or nil if you don't want a background view. - @discussion This method is called every time the list adapter is updated. You are free to return new views every time, + @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 adding the background view and maintaining its visibility. */ diff --git a/Source/IGListAdapterUpdaterDelegate.h b/Source/IGListAdapterUpdaterDelegate.h index e27228d1..3b56bd69 100644 --- a/Source/IGListAdapterUpdaterDelegate.h +++ b/Source/IGListAdapterUpdaterDelegate.h @@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN @param updates The batch updates that were applied to the collection view. @param collectionView The collection view that performed the batch updates. - @discussion This event is called in the completion block of the batch update. + @note This event is called in the completion block of the batch update. */ - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater didPerformBatchUpdates:(IGListBatchUpdateData *)updates withCollectionView:(UICollectionView *)collectionView; @@ -46,7 +46,7 @@ NS_ASSUME_NONNULL_BEGIN @param indexPaths An array of index paths that will be inserted. @param collectionView The collection view that will perform the insert. - @discussion This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. + @note This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. */ - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater willInsertIndexPaths:(NSArray *)indexPaths collectionView:(UICollectionView *)collectionView; @@ -57,7 +57,7 @@ NS_ASSUME_NONNULL_BEGIN @param indexPaths An array of index paths that will be deleted. @param collectionView The collection view that will perform the delete. - @discussion This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. + @note This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. */ - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater willDeleteIndexPaths:(NSArray *)indexPaths collectionView:(UICollectionView *)collectionView; @@ -68,7 +68,7 @@ NS_ASSUME_NONNULL_BEGIN @param indexPaths An array of index paths that will be reloaded. @param collectionView The collection view that will perform the reload. - @discussion This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. + @note This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. */ - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater willReloadIndexPaths:(NSArray *)indexPaths collectionView:(UICollectionView *)collectionView; @@ -79,7 +79,7 @@ NS_ASSUME_NONNULL_BEGIN @param sections The sections that will be reloaded @param collectionView The collection view that will perform the reload. - @discussion This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. + @note This event is only sent when outside of -[UICollectionView performBatchUpdates:completion:]. */ - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater willReloadSections:(NSIndexSet *)sections collectionView:(UICollectionView *)collectionView; diff --git a/Source/IGListCollectionContext.h b/Source/IGListCollectionContext.h index c491e9b5..20a87c77 100644 --- a/Source/IGListCollectionContext.h +++ b/Source/IGListCollectionContext.h @@ -212,7 +212,7 @@ NS_ASSUME_NONNULL_BEGIN @param updates A block containing all of the cell updates. @param completion An optional completion block to execute when the updates are finished. - @discussion Use this method to batch cell updates (inserts, deletes, reloads) into a single transaction. This lets you + @note Use this method to batch cell updates (inserts, deletes, reloads) into a single transaction. This lets you make many changes to your data store and perform all the transitions at once. For example, inside your section controllers, you may want to delete /and/ insert into the data source that backs your diff --git a/Source/IGListDiffable.h b/Source/IGListDiffable.h index ae6fb517..e9e7e608 100644 --- a/Source/IGListDiffable.h +++ b/Source/IGListDiffable.h @@ -20,7 +20,7 @@ @return A key that can be used to uniquely identify the object. - @discussion Two objects may share the same identifier, but are not equal. A common pattern is to import IGListCommon.h + @note Two objects may share the same identifier, but are not equal. A common pattern is to import IGListCommon.h and use the NSObject category for automatic conformance. However this means that objects will be identified on their pointer value so finding updates becomes impossible. diff --git a/Source/IGListSectionController.h b/Source/IGListSectionController.h index 22a2a827..ca3c69a4 100644 --- a/Source/IGListSectionController.h +++ b/Source/IGListSectionController.h @@ -23,7 +23,7 @@ /** The view controller housing the adapter that created this section controller. - @discussion Use this view controller to push, pop, present, or do other custom transitions. It is considered very bad + @note Use this view controller to push, pop, present, or do other custom transitions. It is considered very bad practice to cast this to a known view controller and call methods on it other than for navigations and transitions. */ @property (nonatomic, weak, nullable, readonly) UIViewController *viewController; @@ -70,7 +70,7 @@ @return An object that conforms to IGListSupplementaryViewSource or nil. - @discussion You may wish to return self if your section controller implements this protocol. + @note You may wish to return self if your section controller implements this protocol. */ @property (nonatomic, weak, nullable) id supplementaryViewSource; @@ -79,7 +79,7 @@ @return An object that conforms to IGListDisplayDelegate or nil. - @discussion You may wish to return self if your section controller implements this protocol. + @note You may wish to return self if your section controller implements this protocol. */ @property (nonatomic, weak, nullable) id displayDelegate; @@ -88,7 +88,7 @@ @return An object that conforms to IGListWorkingRangeDelegate or nil. - @discussion You may wish to return self if your section controller implements this protocol. + @note You may wish to return self if your section controller implements this protocol. */ @property (nonatomic, weak, nullable) id workingRangeDelegate; @@ -97,7 +97,7 @@ @return An object that conforms to IGListDisplayDelegate or nil. - @discussion You may wish to return self if your section controller implements this protocol. + @note You may wish to return self if your section controller implements this protocol. */ @property (nonatomic, weak, nullable) id scrollDelegate; diff --git a/Source/IGListSectionType.h b/Source/IGListSectionType.h index 62a3dbc7..542e2b62 100644 --- a/Source/IGListSectionType.h +++ b/Source/IGListSectionType.h @@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN @return A count of items in the list. - @discussion The count returned is used to drive the number of cells displayed for this list. You are free to change + @note The count returned is used to drive the number of cells displayed for this list. You are free to change this value between data loading passes. */ - (NSInteger)numberOfItems; @@ -47,7 +47,7 @@ NS_ASSUME_NONNULL_BEGIN @return The size for the item at index. - @discussion The returned size is not garaunteed to be used. The feed implementation may query list items for their + @note The returned size is not garaunteed to be used. The feed implementation may query list items for their layout information at will, or use its own layout metrics. For example, consider a dynamic-text sized feed vs. a fixed height-and-width grid feed. The former will ask each IGListSectionType for a size, and the latter will likely not. */ @@ -60,7 +60,7 @@ NS_ASSUME_NONNULL_BEGIN @return A configured UICollectionViewCell subclass. - @discussion This is your opportunity to do any cell setup and configuration. The infrastructure requests a cell when it + @note This is your opportunity to do any cell setup and configuration. The infrastructure requests a cell when it will be used on screen. You should never allocate new cells in this method, instead on the provided adapter call -dequeCellClass:forIndexPath: which either deques a cell from the UICollectionView or creates a new one for you. */ @@ -71,7 +71,7 @@ NS_ASSUME_NONNULL_BEGIN @param object The object mapped to this section controller. - @discussion When this method is called, all available contexts and configurations have been set for the section + @note When this method is called, all available contexts and configurations have been set for the section controller. Also, depending on the updating strategy used, your item models may have changed objects in memory, so you can use this event to update the object stored on your section controller. @@ -84,7 +84,7 @@ NS_ASSUME_NONNULL_BEGIN @param index The index of the selected cell. - @discussion Implementation of this method is required for compile-time safety, but you are free to do nothing. + @note Implementation of this method is required for compile-time safety, but you are free to do nothing. */ - (void)didSelectItemAtIndex:(NSInteger)index; diff --git a/Source/IGListStackedSectionController.h b/Source/IGListStackedSectionController.h index c9806775..d9fca4fe 100644 --- a/Source/IGListStackedSectionController.h +++ b/Source/IGListStackedSectionController.h @@ -28,7 +28,7 @@ IGLK_SUBCLASSING_RESTRICTED @param sectionControllers An array of section controllers that make up the stack. - @discussion The order of the section controllers dictates the order in which they appear. The first section controller + @note The order of the section controllers dictates the order in which they appear. The first section controller that is the supplementary source decides which supplementary views get displayed. */ - (instancetype)initWithSectionControllers:(NSArray *> *)sectionControllers NS_DESIGNATED_INITIALIZER; diff --git a/Source/IGListSupplementaryViewSource.h b/Source/IGListSupplementaryViewSource.h index 5df2de64..b1fc9625 100644 --- a/Source/IGListSupplementaryViewSource.h +++ b/Source/IGListSupplementaryViewSource.h @@ -31,7 +31,7 @@ NS_ASSUME_NONNULL_BEGIN @param elementKind The kind of supplementary view being requested @param index The index for the row being requested. - @discussion This is your opportunity to do any supplementary view setup and configuration. + @note This is your opportunity to do any supplementary view setup and configuration. @warning You should never allocate new views in this method. Instead deque a view from the `IGListCollectionContext`. */ diff --git a/Source/IGListUpdatingDelegate.h b/Source/IGListUpdatingDelegate.h index 67b78616..7a2f1cde 100644 --- a/Source/IGListUpdatingDelegate.h +++ b/Source/IGListUpdatingDelegate.h @@ -29,7 +29,7 @@ typedef void (^IGListReloadUpdateBlock)(); @return Pointer functions for looking up an object in a collection. - @discussion Since the updating delegate is responsible for transitioning between object sets, it becomes the "source of + @note Since the updating delegate is responsible for transitioning between object sets, it becomes the "source of truth" for how objects and their corresponding section controllers are mapped. This allows the updater to control if objects are looked up by pointer, or more traditionally, with hash/isEqual. @@ -48,7 +48,7 @@ typedef void (^IGListReloadUpdateBlock)(); @param objectTransitionBlock A block that must be called when the adapter applies changes to the collection view. @param completion A completion block to execute when the update is finished. - @discussion Implementations determine how to transition between objects. You can perform a diff on the objects, reload + @note Implementations determine how to transition between objects. You can perform a diff on the objects, reload each section, or simply call -reloadData on the collection view. In the end, the collection view must be setup with a section for each object in the toObjects array.