From 3992e9b09b2f668f2aff79a3e3ebaca91ae6be38 Mon Sep 17 00:00:00 2001 From: Huy Nguyen Date: Sun, 12 Jul 2015 12:33:37 +0700 Subject: [PATCH] [appledoc] Fix all remaining warnings. --- AsyncDisplayKit/ASCollectionView.h | 82 ++++++++++++++-- AsyncDisplayKit/ASDisplayNode.h | 6 +- AsyncDisplayKit/ASTableView.h | 94 +++++++++++++++++-- AsyncDisplayKit/Layout/ASCenterLayoutSpec.h | 11 ++- AsyncDisplayKit/Layout/ASDimension.h | 7 +- AsyncDisplayKit/Layout/ASLayout.h | 23 ++++- AsyncDisplayKit/Layout/ASLayoutable.h | 5 + AsyncDisplayKit/Layout/ASStackLayoutDefines.h | 4 + AsyncDisplayKit/Layout/ASStackLayoutSpec.h | 5 + AsyncDisplayKit/Layout/ASStaticLayoutSpec.h | 29 ++++-- 10 files changed, 237 insertions(+), 29 deletions(-) diff --git a/AsyncDisplayKit/ASCollectionView.h b/AsyncDisplayKit/ASCollectionView.h index 8254a95b64..ed2526ff95 100644 --- a/AsyncDisplayKit/ASCollectionView.h +++ b/AsyncDisplayKit/ASCollectionView.h @@ -95,25 +95,95 @@ - (void)reloadData; /** - * Section updating. + * Inserts one or more sections. * - * All operations are asynchronous and thread safe. You can call it from background thread (it is recommendated) and the UI collection - * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called. + * @param sections An index set that specifies the sections to insert. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. */ - (void)insertSections:(NSIndexSet *)sections; + +/** + * Deletes one or more sections. + * + * @param sections An index set that specifies the sections to delete. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)deleteSections:(NSIndexSet *)sections; + +/** + * Reloads the specified sections. + * + * @param sections An index set that specifies the sections to reload. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)reloadSections:(NSIndexSet *)sections; + +/** + * Moves a section to a new location. + * + * @param section The index of the section to move. + * + * @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 collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection; /** - * Items updating. + * Inserts items at the locations identified by an array of index paths. * - * All operations are asynchronous and thread safe. You can call it from background thread (it is recommendated) and the UI collection - * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called. + * @param indexPaths An array of NSIndexPath objects, each representing an item index and section index that together identify an item. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. */ - (void)insertItemsAtIndexPaths:(NSArray *)indexPaths; + +/** + * Deletes the items specified by an array of index paths. + * + * @param indexPaths An array of NSIndexPath objects identifying the items to delete. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)deleteItemsAtIndexPaths:(NSArray *)indexPaths; + +/** + * Reloads the specified items. + * + * @param indexPaths An array of NSIndexPath objects identifying the items to reload. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)reloadItemsAtIndexPaths:(NSArray *)indexPaths; + +/** + * Moves the item at a specified location to a destination location. + * + * @param indexPath The index path identifying the item to move. + * + * @param newIndexPath The index path that is the destination of the move for the item. + * + * @discussion This operation is asynchronous and thread safe. You can call it from background thread (it is recommendated) + * and the UI collection view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes + * before this method is called. + */ - (void)moveItemAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath; /** diff --git a/AsyncDisplayKit/ASDisplayNode.h b/AsyncDisplayKit/ASDisplayNode.h index e67b1fc512..fa052b3db9 100644 --- a/AsyncDisplayKit/ASDisplayNode.h +++ b/AsyncDisplayKit/ASDisplayNode.h @@ -144,7 +144,7 @@ typedef CALayer *(^ASDisplayNodeLayerBlock)(); * -measureWithSizeRange: caches results from -calculateLayoutThatFits:. Calling this method may * be expensive if result is not cached. * - * @see [ASDisplayNode(Subclassing) measureWithSizeRange:] + * @see measureWithSizeRange: * @see [ASDisplayNode(Subclassing) calculateLayoutThatFits:] */ - (CGSize)measure:(CGSize)constrainedSize; @@ -361,7 +361,7 @@ typedef CALayer *(^ASDisplayNodeLayerBlock)(); * This method is used to notify the node that it should purge any content that is both expensive to fetch and to * retain in memory. * - * @see ASDisplayNode(Subclassing):clearFetchedData and fetchData + * @see [ASDisplayNode(Subclassing) clearFetchedData] and [ASDisplayNode(Subclassing) fetchData] */ - (void)recursivelyClearFetchedData; @@ -370,7 +370,7 @@ typedef CALayer *(^ASDisplayNodeLayerBlock)(); * * @discussion Fetches content from remote sources for the current node and all subnodes. * - * @see ASDisplayNode(Subclassing):fetchData and clearFetchedData + * @see [ASDisplayNode(Subclassing) fetchData] and [ASDisplayNode(Subclassing) clearFetchedData] */ - (void)recursivelyFetchData; diff --git a/AsyncDisplayKit/ASTableView.h b/AsyncDisplayKit/ASTableView.h index 1e0534c83b..f8d9a60f7d 100644 --- a/AsyncDisplayKit/ASTableView.h +++ b/AsyncDisplayKit/ASTableView.h @@ -103,25 +103,107 @@ - (void)endUpdates; /** - * Section updating. + * Inserts one or more sections, with an option to animate the insertion. * - * All operations are asynchronous and thread safe. You can call it from background thread (it is recommendated) and the UI collection - * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called. + * @param sections An index set that specifies the sections to insert. + * + * @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 + * before this method is called. */ - (void)insertSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Deletes one or more sections, with an option to animate the deletion. + * + * @param sections An index set that specifies the sections to delete. + * + * @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 + * before this method is called. + */ - (void)deleteSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Reloads the specified sections using a given animation effect. + * + * @param sections An index set that specifies the sections to reload. + * + * @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 + * before this method is called. + */ - (void)reloadSections:(NSIndexSet *)sections withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Moves a section to a new location. + * + * @param section The index of the section to move. + * + * @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 + * before this method is called. + */ - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection; /** - * Row updating. + * Inserts rows at the locations identified by an array of index paths, with an option to animate the insertion. * - * All operations are asynchronous and thread safe. You can call it from background thread (it is recommendated) and the UI collection - * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called. + * @param indexPaths An array of NSIndexPath objects, each representing a row index and section index that together identify a row. + * + * @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 + * before this method is called. */ - (void)insertRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Deletes the rows specified by an array of index paths, with an option to animate the deletion. + * + * @param indexPaths An array of NSIndexPath objects identifying the rows to delete. + * + * @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 + * before this method is called. + */ - (void)deleteRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Reloads the specified rows using a given animation effect. + * + * @param indexPaths An array of NSIndexPath objects identifying the rows to reload. + * + * @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 + * before this method is called. + */ - (void)reloadRowsAtIndexPaths:(NSArray *)indexPaths withRowAnimation:(UITableViewRowAnimation)animation; + +/** + * Moves the row at a specified location to a destination location. + * + * @param indexPath The index path identifying the row to move. + * + * @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 + * before this method is called. + */ - (void)moveRowAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath; /** diff --git a/AsyncDisplayKit/Layout/ASCenterLayoutSpec.h b/AsyncDisplayKit/Layout/ASCenterLayoutSpec.h index 5afc73197a..84e015ac57 100644 --- a/AsyncDisplayKit/Layout/ASCenterLayoutSpec.h +++ b/AsyncDisplayKit/Layout/ASCenterLayoutSpec.h @@ -10,6 +10,7 @@ #import +/** How the child is centered within the spec. */ typedef NS_OPTIONS(NSUInteger, ASCenterLayoutSpecCenteringOptions) { /** The child is positioned in {0,0} relatively to the layout bounds */ ASCenterLayoutSpecCenteringNone = 0, @@ -21,6 +22,7 @@ typedef NS_OPTIONS(NSUInteger, ASCenterLayoutSpecCenteringOptions) { ASCenterLayoutSpecCenteringXY = ASCenterLayoutSpecCenteringX | ASCenterLayoutSpecCenteringY }; +/** How much space the spec will take up. */ typedef NS_OPTIONS(NSUInteger, ASCenterLayoutSpecSizingOptions) { /** The spec will take up the maximum size possible */ ASCenterLayoutSpecSizingOptionDefault, @@ -36,8 +38,13 @@ typedef NS_OPTIONS(NSUInteger, ASCenterLayoutSpecSizingOptions) { @interface ASCenterLayoutSpec : ASLayoutSpec /** - @param centeringOptions, see ASCenterLayoutSpecCenteringOptions. - @param child The child to center. + * Initializer. + * + * @param centeringOptions How the child is centered. + * + * @param sizingOptions How much space will be taken up. + * + * @param child The child to center. */ + (instancetype)newWithCenteringOptions:(ASCenterLayoutSpecCenteringOptions)centeringOptions sizingOptions:(ASCenterLayoutSpecSizingOptions)sizingOptions diff --git a/AsyncDisplayKit/Layout/ASDimension.h b/AsyncDisplayKit/Layout/ASDimension.h index 6c11aa7701..590f9486de 100644 --- a/AsyncDisplayKit/Layout/ASDimension.h +++ b/AsyncDisplayKit/Layout/ASDimension.h @@ -13,14 +13,11 @@ /** A dimension relative to constraints to be provided in the future. - A RelativeDimension can be one of two types: - - "Points" - Just a number. It will always resolve to exactly this amount. This is the default type. - - "Percent" - Multiplied to a provided parent amount to resolve a final amount. */ typedef NS_ENUM(NSInteger, ASRelativeDimensionType) { + /** Just a number. It will always resolve to exactly this amount. This is the default type. */ ASRelativeDimensionTypePoints, + /** Multiplied to a provided parent amount to resolve a final amount. */ ASRelativeDimensionTypePercent, }; diff --git a/AsyncDisplayKit/Layout/ASLayout.h b/AsyncDisplayKit/Layout/ASLayout.h index 3cc5158840..a3d32feddc 100644 --- a/AsyncDisplayKit/Layout/ASLayout.h +++ b/AsyncDisplayKit/Layout/ASLayout.h @@ -32,16 +32,33 @@ extern BOOL CGPointIsNull(CGPoint point); */ @property (nonatomic, readonly) NSArray *sublayouts; +/** + * Initializer. + * + * @param layoutableObject The backing ASLayoutable object. + * + * @param size The size of this layout. + * + * @param position The posiion of this layout within its parent (if available). + * + * @param sublayouts Sublayouts belong to the new layout. + */ + (instancetype)newWithLayoutableObject:(id)layoutableObject size:(CGSize)size position:(CGPoint)position sublayouts:(NSArray *)sublayouts; /** - * Convenience that has CGPointNull position. + * Convenience initializer that has CGPointNull position. * Best used by ASDisplayNode subclasses that are manually creating a layout for -calculateLayoutThatFits:, * or for ASLayoutSpec subclasses that are referencing the "self" level in the layout tree, * or for creating a sublayout of which the position is yet to be determined. + * + * @param layoutableObject The backing ASLayoutable object. + * + * @param size The size of this layout. + * + * @param sublayouts Sublayouts belong to the new layout. */ + (instancetype)newWithLayoutableObject:(id)layoutableObject size:(CGSize)size @@ -51,6 +68,10 @@ extern BOOL CGPointIsNull(CGPoint point); * Convenience that has CGPointNull position and no sublayouts. * Best used for creating a layout that has no sublayouts, and is either a root one * or a sublayout of which the position is yet to be determined. + * + * @param layoutableObject The backing ASLayoutable object. + * + * @param size The size of this layout. */ + (instancetype)newWithLayoutableObject:(id)layoutableObject size:(CGSize)size; diff --git a/AsyncDisplayKit/Layout/ASLayoutable.h b/AsyncDisplayKit/Layout/ASLayoutable.h index ea0acedabb..30bf7af5e8 100644 --- a/AsyncDisplayKit/Layout/ASLayoutable.h +++ b/AsyncDisplayKit/Layout/ASLayoutable.h @@ -13,6 +13,11 @@ @class ASLayout; +/** + * The ASLayoutable protocol declares a method for measuring the layout of an object. A class must implement the method + * so that instances of that class can be used to build layout trees. The protocol also provides information + * about how an object should be laid out within an ASStackLayoutSpec. + */ @protocol ASLayoutable /** diff --git a/AsyncDisplayKit/Layout/ASStackLayoutDefines.h b/AsyncDisplayKit/Layout/ASStackLayoutDefines.h index 040d8ac01a..6663ad2ae3 100644 --- a/AsyncDisplayKit/Layout/ASStackLayoutDefines.h +++ b/AsyncDisplayKit/Layout/ASStackLayoutDefines.h @@ -15,8 +15,12 @@ typedef NS_ENUM(NSUInteger, ASStackLayoutAlignSelf) { /** Inherit alignment value from containing stack. */ ASStackLayoutAlignSelfAuto, + /** Align to start of cross axis */ ASStackLayoutAlignSelfStart, + /** Align with end of cross axis */ ASStackLayoutAlignSelfEnd, + /** Center on cross axis */ ASStackLayoutAlignSelfCenter, + /** Expand to fill cross axis */ ASStackLayoutAlignSelfStretch, }; diff --git a/AsyncDisplayKit/Layout/ASStackLayoutSpec.h b/AsyncDisplayKit/Layout/ASStackLayoutSpec.h index 83322b8de5..29f20603c5 100644 --- a/AsyncDisplayKit/Layout/ASStackLayoutSpec.h +++ b/AsyncDisplayKit/Layout/ASStackLayoutSpec.h @@ -10,8 +10,11 @@ #import +/** The direction children are stacked in */ typedef NS_ENUM(NSUInteger, ASStackLayoutDirection) { + /** Children are stacked vertically */ ASStackLayoutDirectionVertical, + /** Children are stacked horizontally */ ASStackLayoutDirectionHorizontal, }; @@ -34,6 +37,7 @@ typedef NS_ENUM(NSUInteger, ASStackLayoutJustifyContent) { ASStackLayoutJustifyContentEnd, }; +/** Orientation of children along cross axis */ typedef NS_ENUM(NSUInteger, ASStackLayoutAlignItems) { /** Align children to start of cross axis */ ASStackLayoutAlignItemsStart, @@ -68,6 +72,7 @@ typedef struct { justifyContent determines how children are laid out. For example: + - Suppose stacking direction is Vertical, min-width=100, max-width=300, min-height=200, max-height=500. - All children are laid out with min-width=100, max-width=300, min-height=0, max-height=INFINITY. - If the sum of the childrens' heights is less than 200, children with flexGrow are flexed larger. diff --git a/AsyncDisplayKit/Layout/ASStaticLayoutSpec.h b/AsyncDisplayKit/Layout/ASStaticLayoutSpec.h index 09815c648b..259c32c4d6 100644 --- a/AsyncDisplayKit/Layout/ASStaticLayoutSpec.h +++ b/AsyncDisplayKit/Layout/ASStaticLayoutSpec.h @@ -11,6 +11,10 @@ #import #import +/** + * An ASStaticLayoutSpecChild object wraps an ASLayoutable object and provides position and size information, + * to be used as a child of an ASStaticLayoutSpec. + */ @interface ASStaticLayoutSpecChild : NSObject @property (nonatomic, readonly) CGPoint position; @@ -21,20 +25,33 @@ */ @property (nonatomic, readonly) ASRelativeSizeRange size; +/** + * Initializer. + * + * @param position The position of this child within its parent spec. + * + * @param layoutableObject The backing ASLayoutable object of this child. + * + * @param size The size range that this child's size is trstricted according to. + */ + (instancetype)newWithPosition:(CGPoint)position layoutableObject:(id)layoutableObject size:(ASRelativeSizeRange)size; /** - Convenience with default size is Unconstrained in both dimensions, which sets the child's min size to zero - and max size to the maximum available space it can consume without overflowing the spec's bounds. + * Convenience initializer with default size is Unconstrained in both dimensions, which sets the child's min size to zero + * and max size to the maximum available space it can consume without overflowing the spec's bounds. + * + * @param position The position of this child within its parent spec. + * + * @param layoutableObject The backing ASLayoutable object of this child. */ + (instancetype)newWithPosition:(CGPoint)position layoutableObject:(id)layoutableObject; @end -/* - A layout spec that positions children at fixed positions. - - Computes a size that is the union of all childrens' frames. +/** + * A layout spec that positions children at fixed positions. + * + * Computes a size that is the union of all childrens' frames. */ @interface ASStaticLayoutSpec : ASLayoutSpec