[appledoc] Fix all remaining warnings.

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
+ * @param sections An index set that specifies the sections to insert.
- * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called.
+ *
+ * @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
+ * @param indexPaths An array of NSIndexPath objects, each representing an item index and section index that together identify an item.
- * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called.
+ *
+ * @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;
 
 /**

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;
 

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
+ * @param sections An index set that specifies the sections to insert.
- * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called.
+ * 
+ * @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
+ * @param indexPaths An array of NSIndexPath objects, each representing a row index and section index that together identify a row.
- * view will be updated asynchronously. The asyncDataSource must be updated to reflect the changes before these methods are called.
+ *
+ * @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;
 
 /**

AsyncDisplayKit/Layout/ASCenterLayoutSpec.h

@@ -10,6 +10,7 @@
 
 #import <AsyncDisplayKit/ASLayoutSpec.h>
 
+/** 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.
+ * Initializer.
- @param child The child to center.
+ *
+ * @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

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,
 };
 

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<ASLayoutable>)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<ASLayoutable>)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<ASLayoutable>)layoutableObject size:(CGSize)size;
 

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 <NSObject>
 
 /** 

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,
 };

AsyncDisplayKit/Layout/ASStackLayoutSpec.h

@@ -10,8 +10,11 @@
 
 #import <AsyncDisplayKit/ASLayoutSpec.h>
 
+/** 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.

AsyncDisplayKit/Layout/ASStaticLayoutSpec.h

@@ -11,6 +11,10 @@
 #import <AsyncDisplayKit/ASLayoutSpec.h>
 #import <AsyncDisplayKit/ASRelativeSize.h>
 
+/** 
+ * 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<ASLayoutable>)layoutableObject size:(ASRelativeSizeRange)size;
 
 /**
- Convenience with default size is Unconstrained in both dimensions, which sets the child's min size to zero 
+ * 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.
+ * 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<ASLayoutable>)layoutableObject;
 
 @end
 
-/*
+/**
- A layout spec that positions children at fixed positions.
+ * A layout spec that positions children at fixed positions.
-
+ * 
- Computes a size that is the union of all childrens' frames.
+ * Computes a size that is the union of all childrens' frames.
  */
 @interface ASStaticLayoutSpec : ASLayoutSpec