From 9735d611e8faacb53cb18c7698d0aef06aa975ec Mon Sep 17 00:00:00 2001 From: Andrew Monshizadeh Date: Fri, 31 Mar 2017 12:59:23 -0700 Subject: [PATCH] Nitpicky comment fixes Summary: Mainly this addresses clarity of a few comments, line breaks at weird places, and style differences within a single file. Just comments and including JetBrains `.idea` config folder in the `gitignore`. - [X] All tests pass. Demo project builds and runs. - [X] I added tests, an experiment, or detailed why my change isn't tested. - [N/A] I added an entry to the `CHANGELOG.md` for any breaking changes, enhancements, or bug fixes. - [N/A] I have reviewed the [contributing guide](https://github.com/Instagram/IGListKit/blob/master/.github/CONTRIBUTING.md) Closes https://github.com/Instagram/IGListKit/pull/600 Differential Revision: D4810628 Pulled By: jessesquires fbshipit-source-id: fce445c0253f592a43045ae098e440d41c166993 --- .gitignore | 3 +++ Source/IGListAdapter.h | 22 +++++++++++----------- Source/IGListAdapterDataSource.h | 2 +- Source/IGListAdapterUpdater.h | 2 +- Source/IGListAdapterUpdater.m | 4 ++-- Source/IGListAdapterUpdaterDelegate.h | 2 +- Source/IGListBindable.h | 2 +- Source/IGListCollectionContext.h | 16 ++++++++-------- Source/IGListCollectionView.h | 4 ++-- Source/IGListCollectionViewLayout.h | 10 ++++++---- Source/IGListDisplayDelegate.h | 2 +- Source/IGListReloadDataUpdater.h | 2 +- Source/IGListScrollDelegate.h | 2 +- Source/IGListSectionType.h | 2 +- Source/IGListSingleSectionController.h | 7 ++++--- Source/IGListStackedSectionController.h | 8 ++++---- Source/Internal/IGListSectionMap.h | 2 +- 17 files changed, 49 insertions(+), 43 deletions(-) diff --git a/.gitignore b/.gitignore index fd433d36a..6a1f6db9b 100644 --- a/.gitignore +++ b/.gitignore @@ -52,3 +52,6 @@ Carthage/Build # Bundler .bundle vendor + +# Jetbrains +.idea diff --git a/Source/IGListAdapter.h b/Source/IGListAdapter.h index 6d463661b..85bcd01d8 100644 --- a/Source/IGListAdapter.h +++ b/Source/IGListAdapter.h @@ -24,9 +24,9 @@ NS_ASSUME_NONNULL_BEGIN /** - A block to execute when list updates completes. + A block to execute when the list updates are completed. - @param finished Specifies whether or not the updates finished. + @param finished Specifies whether or not the update animations completed successfully. */ typedef void (^IGListUpdaterCompletion)(BOOL finished); @@ -52,7 +52,7 @@ IGLK_SUBCLASSING_RESTRICTED @property (nonatomic, nullable, weak) IGListCollectionView *collectionView; /** - The object that acts as the data source for the list adapter. + The object that acts as the data source for the adapter. */ @property (nonatomic, nullable, weak) id dataSource; @@ -74,7 +74,7 @@ IGLK_SUBCLASSING_RESTRICTED @property (nonatomic, nullable, weak) id scrollViewDelegate; /** - The updater for this list adapter. + The updater for the adapter. */ @property (nonatomic, strong, readonly) id updater; @@ -104,11 +104,11 @@ IGLK_SUBCLASSING_RESTRICTED workingRangeSize:(NSInteger)workingRangeSize NS_DESIGNATED_INITIALIZER; /** - Perform an update from the previous state of the data source. This is analagous to calling + Perform an update from the previous state of the data source. This is analogous to calling `-[UICollectionView performBatchUpdates:completion:]`. @param animated A flag indicating if the transition should be animated. - @param completion The block to execute when the update completes. + @param completion The block to execute when the updates complete. */ - (void)performUpdatesAnimated:(BOOL)animated completion:(nullable IGListUpdaterCompletion)completion; @@ -131,7 +131,7 @@ IGLK_SUBCLASSING_RESTRICTED @param section A section in the list. - @return An section controller or `nil` if the section does not exist. + @return A section controller or `nil` if the section does not exist. */ - (nullable IGListSectionController *)sectionControllerForSection:(NSInteger)section; @@ -149,7 +149,7 @@ IGLK_SUBCLASSING_RESTRICTED @param object An object from the data source. - @return An section controller or `nil` if `object` is not in the list. + @return A section controller or `nil` if `object` is not in the list. @see `-[IGListAdapterDataSource listAdapter:sectionControllerForObject:]` */ @@ -160,7 +160,7 @@ IGLK_SUBCLASSING_RESTRICTED @param sectionController A section controller in the list. - @return The object for the specified section controller, or nil if not found. + @return The object for the specified section controller, or `nil` if not found. */ - (nullable id)objectForSectionController:(IGListSectionController *)sectionController; @@ -183,7 +183,7 @@ IGLK_SUBCLASSING_RESTRICTED - (NSInteger)sectionForObject:(id)object; /** - Returns a copy of all the objects currently powering the adapter. + Returns a copy of all the objects currently driving the adapter. @return An array of objects. */ @@ -213,7 +213,7 @@ IGLK_SUBCLASSING_RESTRICTED - (NSArray *)visibleCellsForObject:(id)object; /** - Scrolls to the sepcified object in the list adapter. + Scrolls to the specified object in the list adapter. @param object The object to which to scroll. @param supplementaryKinds The types of supplementary views in the section. diff --git a/Source/IGListAdapterDataSource.h b/Source/IGListAdapterDataSource.h index f45ca43eb..7e2eb92db 100644 --- a/Source/IGListAdapterDataSource.h +++ b/Source/IGListAdapterDataSource.h @@ -45,7 +45,7 @@ NS_ASSUME_NONNULL_BEGIN 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. + guarantees this. */ - (IGListSectionController *)listAdapter:(IGListAdapter *)listAdapter sectionControllerForObject:(id)object; diff --git a/Source/IGListAdapterUpdater.h b/Source/IGListAdapterUpdater.h index 7ae34faeb..5f1b7a76e 100644 --- a/Source/IGListAdapterUpdater.h +++ b/Source/IGListAdapterUpdater.h @@ -18,7 +18,7 @@ NS_ASSUME_NONNULL_BEGIN /** An `IGListAdapterUpdater` is a concrete type that conforms to `IGListUpdatingDelegate`. - It is an out-of-box upater for `IGListAdapter` objects to use. + It is an out-of-box updater for `IGListAdapter` objects to use. @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 diff --git a/Source/IGListAdapterUpdater.m b/Source/IGListAdapterUpdater.m index 6e8ac443a..a3017dd65 100644 --- a/Source/IGListAdapterUpdater.m +++ b/Source/IGListAdapterUpdater.m @@ -65,7 +65,7 @@ - (void)performReloadDataWithCollectionView:(UICollectionView *)collectionView { } // execute all stored item update blocks even if we are just calling reloadData. the actual collection view - // mutations will be discarded, but clients are encouraged to put their actually /data/ mutations inside the + // mutations will be discarded, but clients are encouraged to put their actual /data/ mutations inside the // update block as well, so if we don't execute the block the changes will never happen for (IGListItemUpdateBlock itemUpdateBlock in batchUpdates.itemUpdateBlocks) { itemUpdateBlock(); @@ -305,7 +305,7 @@ - (void)cleanStateBeforeUpdates { // remove indexpath/item changes self.objectTransitionBlock = nil; - // removes all object completion blocks. done before updates to start collecting completion blocks for coaslesced + // removes all object completion blocks. done before updates to start collecting completion blocks for coalesced // or re-entrant object updates [self.completionBlocks removeAllObjects]; } diff --git a/Source/IGListAdapterUpdaterDelegate.h b/Source/IGListAdapterUpdaterDelegate.h index 4acea98ea..aad82f680 100644 --- a/Source/IGListAdapterUpdaterDelegate.h +++ b/Source/IGListAdapterUpdaterDelegate.h @@ -29,7 +29,7 @@ NS_ASSUME_NONNULL_BEGIN - (void)listAdapterUpdater:(IGListAdapterUpdater *)listAdapterUpdater willPerformBatchUpdatesWithCollectionView:(UICollectionView *)collectionView; /** - Notifies the delegate that the updater succesfully finished `-[UICollectionView performBatchUpdates:completion:]`. + Notifies the delegate that the updater successfully finished `-[UICollectionView performBatchUpdates:completion:]`. @param listAdapterUpdater The adapter updater owning the transition. @param updates The batch updates that were applied to the collection view. diff --git a/Source/IGListBindable.h b/Source/IGListBindable.h index 62b17dbac..3867ce80b 100644 --- a/Source/IGListBindable.h +++ b/Source/IGListBindable.h @@ -19,7 +19,7 @@ NS_ASSUME_NONNULL_BEGIN /** Tells the cell to configure itself with the given view model. - @param viewModel The view model for the cel. + @param viewModel The view model for the cell. @note The view model can change many times throughout the lifetime of a cell as the model values change and the cell is reused. Implementations should use only this method to do their configuration. diff --git a/Source/IGListCollectionContext.h b/Source/IGListCollectionContext.h index 32c3ce0f7..70f2d4aef 100644 --- a/Source/IGListCollectionContext.h +++ b/Source/IGListCollectionContext.h @@ -102,7 +102,7 @@ NS_ASSUME_NONNULL_BEGIN /** Returns the section index of an section controller. - @param sectionController An section controller object. + @param sectionController A section controller object. @return The section index of the controller if found, otherwise `NSNotFound`. */ @@ -156,10 +156,10 @@ NS_ASSUME_NONNULL_BEGIN /** Dequeues a supplementary view from the collection view reuse pool. - @param elementKind The kind of supplementary veiw. + @param elementKind The kind of supplementary view. @param sectionController The section controller requesting this information. @param viewClass The class of the supplementary view. - @param index The index of the supplementary vew. + @param index The index of the supplementary view. @return A supplementary view dequeued from the reuse pool or a newly created one. @@ -173,10 +173,10 @@ NS_ASSUME_NONNULL_BEGIN /** Dequeues a supplementary view from the collection view reuse pool. - @param elementKind The kind of supplementary veiw. + @param elementKind The kind of supplementary view. @param identifier The identifier of the supplementary view in storyboard. @param sectionController The section controller requesting this information. - @param index The index of the supplementary vew. + @param index The index of the supplementary view. @return A supplementary view dequeued from the reuse pool or a newly created one. */ @@ -187,11 +187,11 @@ NS_ASSUME_NONNULL_BEGIN /** Dequeues a supplementary view from the collection view reuse pool. - @param elementKind The kind of supplementary veiw. + @param elementKind The kind of supplementary view. @param sectionController The section controller requesting this information. @param nibName The name of the nib file. @param bundle The bundle in which to search for the nib file. If `nil`, this method searches the main bundle. - @param index The index of the supplementary vew. + @param index The index of the supplementary view. @return A supplementary view dequeued from the reuse pool or a newly created one. @@ -210,7 +210,7 @@ NS_ASSUME_NONNULL_BEGIN @param completion An optional completion block to execute when the updates are finished. @note This method can be wrapped in `UIView` animation APIs to control the duration or perform without animations. This - will end up calling `-[UICollectionView performBatchUpdates:completion:] internally, so invalidated changes may not be + will end up calling `-[UICollectionView performBatchUpdates:completion:]` internally, so invalidated changes may not be reflected in the cells immediately. */ - (void)invalidateLayoutForSectionController:(IGListSectionController *)sectionController diff --git a/Source/IGListCollectionView.h b/Source/IGListCollectionView.h index 66b060c85..c6fa5c75e 100644 --- a/Source/IGListCollectionView.h +++ b/Source/IGListCollectionView.h @@ -13,8 +13,8 @@ /** This class is never actually used by the `IGListKit` infrastructure. - It exists only to give compiler errors when editing - methods are called on the collection view returned by `-[IGListAdapter collectionView]`. + It exists only to give compiler errors when editing methods are called on the collection view returned by + `-[IGListAdapter collectionView]`. */ IGLK_SUBCLASSING_RESTRICTED @interface IGListCollectionView : UICollectionView diff --git a/Source/IGListCollectionViewLayout.h b/Source/IGListCollectionViewLayout.h index d641adeb4..15d9e0232 100644 --- a/Source/IGListCollectionViewLayout.h +++ b/Source/IGListCollectionViewLayout.h @@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN Sections and items are put into the same horizontal row until the max-x position of an item extends beyond the width of the collection view. When that happens, the item is "newlined" to the next row. The y position of that row is - deteremined by the maximum height (including section insets) of the section/item of the previous row. + determined by the maximum height (including section insets) of the section/item of the previous row. Ex. of a section (2,0) with a large width causing a newline. ``` @@ -81,9 +81,11 @@ NS_ASSUME_NONNULL_BEGIN /** Create and return a new collection view layout. - @param stickyHeaders Set to `YES` to stick section headers to the top of the bounds while scrolling. - @param topContentInset The top content inset used to offset the sticky headers. Ignored if stickyHeaders is `NO`. - @param stretchToEdge Specifies whether to stretch width of last item to right edge when distance from last item to right edge < epsilon(1) + + @param stickyHeaders Set to `YES` to stick section headers to the top of the bounds while scrolling. + @param topContentInset The top content inset used to offset the sticky headers. Ignored if stickyHeaders is `NO`. + @param stretchToEdge Specifies whether to stretch width of last item to right edge when distance from last item to right edge < epsilon(1) + @return A new collection view layout. */ - (instancetype)initWithStickyHeaders:(BOOL)stickyHeaders diff --git a/Source/IGListDisplayDelegate.h b/Source/IGListDisplayDelegate.h index 00321da25..14c57423b 100644 --- a/Source/IGListDisplayDelegate.h +++ b/Source/IGListDisplayDelegate.h @@ -17,7 +17,7 @@ NS_ASSUME_NONNULL_BEGIN /** - Implement this protocol to receive display events for an section controller when it is on screen. + Implement this protocol to receive display events for a section controller when it is on screen. */ @protocol IGListDisplayDelegate diff --git a/Source/IGListReloadDataUpdater.h b/Source/IGListReloadDataUpdater.h index 342732a09..c7ef2508b 100644 --- a/Source/IGListReloadDataUpdater.h +++ b/Source/IGListReloadDataUpdater.h @@ -14,7 +14,7 @@ /** An `IGListReloadDataUpdater` is a concrete type that conforms to `IGListUpdatingDelegate`. - It is an out-of-box upater for `IGListAdapter` objects to use. + It is an out-of-box updater for `IGListAdapter` objects to use. @note This updater performs simple, synchronous updates using `-[UICollectionView reloadData]`. */ diff --git a/Source/IGListScrollDelegate.h b/Source/IGListScrollDelegate.h index d13576f12..f009fcb46 100644 --- a/Source/IGListScrollDelegate.h +++ b/Source/IGListScrollDelegate.h @@ -15,7 +15,7 @@ @protocol IGListSectionType; /** - Implement this protocol to receive display events for an section controller when it is on screen. + Implement this protocol to receive display events for a section controller when it is on screen. */ @protocol IGListScrollDelegate diff --git a/Source/IGListSectionType.h b/Source/IGListSectionType.h index 72193df0f..c45ca97a0 100644 --- a/Source/IGListSectionType.h +++ b/Source/IGListSectionType.h @@ -47,7 +47,7 @@ NS_ASSUME_NONNULL_BEGIN @return The size for the item at index. - @note The returned size is not garaunteed to be used. The implementation may query sections for their + @note The returned size is not guaranteed to be used. The implementation may query sections for their layout information at will, or use its own layout metrics. For example, consider a dynamic-text sized list versus a fixed height-and-width grid. The former will ask each section for a size, and the latter will likely not. */ diff --git a/Source/IGListSingleSectionController.h b/Source/IGListSingleSectionController.h index 7d7cf0561..86c871a32 100644 --- a/Source/IGListSingleSectionController.h +++ b/Source/IGListSingleSectionController.h @@ -30,7 +30,7 @@ typedef void (^IGListSingleSectionCellConfigureBlock)(id item, __kindof UICollec @param item The model for the section. @param collectionContext The collection context for the section. - @return The for the cell. + @return The size for the cell. */ typedef CGSize (^IGListSingleSectionCellSizeBlock)(id item, id _Nullable collectionContext); @@ -54,7 +54,8 @@ typedef CGSize (^IGListSingleSectionCellSizeBlock)(id item, id @@ -79,7 +80,7 @@ IGLK_SUBCLASSING_RESTRICTED Creates a new section controller for a given nib name and bundle that will always have only one cell when present in a list. @param nibName The name of the nib file for the single cell. - @param bundle The bundle in which to search for the nib file. If nil, this method looks for the file in the main bundle. + @param bundle The bundle in which to search for the nib file. If `nil`, this method looks for the file in the main bundle. @param configureBlock A block that configures the cell with the item given to the section controller. @param sizeBlock A block that returns the size for the cell given the collection context. diff --git a/Source/IGListStackedSectionController.h b/Source/IGListStackedSectionController.h index f8cc31822..4b389ccb6 100644 --- a/Source/IGListStackedSectionController.h +++ b/Source/IGListStackedSectionController.h @@ -12,10 +12,10 @@ #import /** - An instance of `IGListStackedSectionController` is a clustered section controller, - composed of many child section controllers. It constructs and routes item-level - indexes to the appropriate child section controller with a local index. This lets you build section controllers made up - of individual units that can be shared and reused with other section controllers. + An instance of `IGListStackedSectionController` is a clustered section controller, composed of many child section + controllers. It constructs and routes item-level indexes to the appropriate child section controller with a local + index. This lets you build section controllers made up of individual units that can be shared and reused with other + section controllers. For example, you can create a "Comments" section controller that displays lists of text that is used alongside photo, video, or slideshow section controllers. You then have four small and manageable section controllers instead of one diff --git a/Source/Internal/IGListSectionMap.h b/Source/Internal/IGListSectionMap.h index 9fe8ba7ee..bc5b5aaa6 100644 --- a/Source/Internal/IGListSectionMap.h +++ b/Source/Internal/IGListSectionMap.h @@ -20,7 +20,7 @@ NS_ASSUME_NONNULL_BEGIN The IGListSectionMap provides a way to map a collection of objects to a collection of section controllers and achieve constant-time lookups O(1). - IGListSectionMap is a mutable object and does not garauntee thread safety. + IGListSectionMap is a mutable object and does not guarantee thread safety. */ IGLK_SUBCLASSING_RESTRICTED @interface IGListSectionMap : NSObject