Merge pull request #653 from rcancro/documentation

Added missing Appledoc documentation

Author: appleguy

AsyncDisplayKit/ASDisplayNode.h

@@ -28,7 +28,7 @@ typedef UIView *(^ASDisplayNodeViewBlock)();
 typedef CALayer *(^ASDisplayNodeLayerBlock)();
 
 /**
- * ASDisplayNode loaded callback block. Used for any additional setup after node's layer/view has been loaded
+ * ASDisplayNode loaded callback block. This block is called BEFORE the -didLoad method and is always called on the main thread.
  */
 typedef void (^ASDisplayNodeDidLoadBlock)(ASDisplayNode *node);
 
@@ -87,7 +87,7 @@ typedef void (^ASDisplayNodeDidLoadBlock)(ASDisplayNode *node);
 /**
  * @abstract Alternative initializer with a block to create the backing layer.
  *
- * @param viewBlock The block that will be used to create the backing layer.
+ * @param layerBlock The block that will be used to create the backing layer.
  *
  * @return An ASDisplayNode instance that loads its layer with the given block that is guaranteed to run on the main
  * queue. The layer will render synchronously and -layout and touch handling methods on the node will not be called.
@@ -97,7 +97,7 @@ typedef void (^ASDisplayNodeDidLoadBlock)(ASDisplayNode *node);
 /**
  * @abstract Alternative initializer with a block to create the backing layer.
  *
- * @param viewBlock The block that will be used to create the backing layer.
+ * @param layerBlock The block that will be used to create the backing layer.
  * @param didLoadBlock The block that will be called after the layer created by the layerBlock is loaded
  *
  * @return An ASDisplayNode instance that loads its layer with the given block that is guaranteed to run on the main

AsyncDisplayKit/Layout/ASLayoutOptions.h

@@ -13,16 +13,58 @@
 
 @protocol ASLayoutable;
 
+/**
+ *  A store for all of the options defined by ASLayoutSpec subclasses. All implementors of ASLayoutable own a
+ *  ASLayoutOptions. When certain layoutSpecs need option values, they are read from this class.
+ *
+ *  Unless you wish to create a custom layout spec, ASLayoutOptions can largerly be ignored. Instead you can access
+ *  the layout option properties exposed in ASLayoutable directly, which will set the values in ASLayoutOptions
+ *  behind the scenes.
+ */
 @interface ASLayoutOptions : NSObject <ASStackLayoutable, ASStaticLayoutable, NSCopying>
 
+/**
+ *  Sets the class name for the ASLayoutOptions subclasses that will be created when a node or layoutSpec's options 
+ *  are first accessed.
+ *
+ *  If you create a custom layoutSpec that includes new options, you will want to subclass ASLayoutOptions to add
+ *  the new layout options for your layoutSpec(s). In order to make sure your subclass is created instead of an 
+ *  instance of ASLayoutOptions, call setDefaultLayoutOptionsClass: early in app launch (applicationDidFinishLaunching:)
+ *  with your subclass's class.
+ *
+ *  @param defaultLayoutOptionsClass The class of ASLayoutOptions that will be lazily created for a node or layout spec.
+ */
 + (void)setDefaultLayoutOptionsClass:(Class)defaultLayoutOptionsClass;
+
+/**
+ *  @return the Class of ASLayoutOptions that will be created for a node or layoutspec. Defaults to [ASLayoutOptions class];
+ */
 + (Class)defaultLayoutOptionsClass;
 
+#pragma mark - Subclasses should implement these!
+/**
+ *  Initializes a new ASLayoutOptions using the given layoutable to assign any intrinsic option values.
+ *  This init function sets a sensible default value for each layout option. If you create a subclass of 
+ *  ASLayoutOptions, your subclass should do the same.
+ *
+ *  @param layoutable The layoutable that will own these options. The layoutable will be used to set any intrinsic
+ *         layoutOptions. For example, if the layoutable is an ASTextNode the ascender/descender values will get set.
+ *
+ *  @return a new instance of ASLayoutOptions
+ */
 - (instancetype)initWithLayoutable:(id<ASLayoutable>)layoutable;
-- (void)setValuesFromLayoutable:(id<ASLayoutable>)layoutable;
 
-#pragma mark - Subclasses should implement these!
-- (void)propagateOptionsFromLayoutOptions:(ASLayoutOptions *)layoutOptions;
+/**
+ *  Copies the values of layoutOptions into self. This is useful when placing a layoutable inside of another. Consider
+ *  an ASTextNode that you want to align to the baseline by putting it in an ASStackLayoutSpec. Before that, you want
+ *  to inset the ASTextNode by placing it in an ASInsetLayoutSpec. An ASInsetLayoutSpec will not have any information
+ *  about the ASTextNode's ascender/descender unless we copy over the layout options from ASTextNode to ASInsetLayoutSpec.
+ *  This is done automatically and should not need to be called directly. It is listed here to make sure that any 
+ *  ASLayoutOptions subclass implements the method.
+ *
+ *  @param layoutOptions The layoutOptions to copy from
+ */
+- (void)copyIntoOptions:(ASLayoutOptions *)layoutOptions;
 
 #pragma mark - ASStackLayoutable
 

AsyncDisplayKit/Layout/ASLayoutOptions.mm

@@ -86,11 +86,11 @@ - (instancetype)initWithLayoutable:(id<ASLayoutable>)layoutable;
 - (id)copyWithZone:(NSZone *)zone
 {
   ASLayoutOptions *copy = [[[self class] alloc] init];
-  [copy propagateOptionsFromLayoutOptions:self];
+  [copy copyIntoOptions:self];
   return copy;
 }
 
-- (void)propagateOptionsFromLayoutOptions:(ASLayoutOptions *)layoutOptions
+- (void)copyIntoOptions:(ASLayoutOptions *)layoutOptions
 {
   ASDN::MutexLocker l(_propertyLock);
   self.flexBasis = layoutOptions.flexBasis;
@@ -125,7 +125,6 @@ - (void)setValuesFromLayoutable:(id<ASLayoutable>)layoutable
   if ([layoutable isKindOfClass:[ASDisplayNode class]]) {
     ASDisplayNode *displayNode = (ASDisplayNode *)layoutable;
     self.sizeRange = ASRelativeSizeRangeMake(ASRelativeSizeMakeWithCGSize(displayNode.preferredFrameSize), ASRelativeSizeMakeWithCGSize(displayNode.preferredFrameSize));
-    self.layoutPosition = displayNode.frame.origin;
 
     if ([layoutable isKindOfClass:[ASTextNode class]]) {
       ASTextNode *textNode = (ASTextNode *)layoutable;

AsyncDisplayKit/Layout/ASLayoutSpec.mm

@@ -82,7 +82,7 @@ - (void)setChild:(id<ASLayoutable>)child;
 
     id<ASLayoutable> finalLayoutable = [child finalLayoutable];
     if (finalLayoutable != child) {
-      [finalLayoutable.layoutOptions propagateOptionsFromLayoutOptions:child.layoutOptions];
+      [finalLayoutable.layoutOptions copyIntoOptions:child.layoutOptions];
       return finalLayoutable;
     }
   }

AsyncDisplayKit/Layout/ASLayoutablePrivate.h

@@ -14,6 +14,10 @@
 @class ASLayoutOptions;
 @protocol ASLayoutable;
 
+/**
+ *  The base protocol for ASLayoutable. Generally the methods/properties in this class do not need to be
+ *  called by the end user and are only called internally. However, there may be a case where the methods are useful.
+ */
 @protocol ASLayoutablePrivate <NSObject>
 
 /**
@@ -35,5 +39,9 @@
  */
 @property (nonatomic, assign) BOOL isFinalLayoutable;
 
+
+/**
+ *  The class that holds all of the layoutOptions set on an ASLayoutable.
+ */
 @property (nonatomic, strong, readonly) ASLayoutOptions *layoutOptions;
 @end

AsyncDisplayKit/Layout/ASStackLayoutable.h

@@ -11,6 +11,9 @@
 #import <AsyncDisplayKit/ASDimension.h>
 #import <AsyncDisplayKit/ASStackLayoutDefines.h>
 
+/**
+ *  Layout options that can be defined for an ASLayoutable being added to a ASStackLayoutSpec.
+ */
 @protocol ASStackLayoutable <NSObject>
 
 /**

AsyncDisplayKit/Layout/ASStaticLayoutable.h

@@ -10,6 +10,9 @@
 
 #import <AsyncDisplayKit/ASRelativeSize.h>
 
+/**
+ *  Layout options that can be defined for an ASLayoutable being added to a ASStaticLayoutSpec. 
+ */
 @protocol ASStaticLayoutable
 
 /**