From 2d30a81a75ddc97151f3b5c57867edc97ac59c1e Mon Sep 17 00:00:00 2001 From: rcancro <@pinterest.com> Date: Tue, 15 Sep 2015 11:03:40 -0700 Subject: [PATCH 1/2] added documentation --- AsyncDisplayKit/Layout/ASLayoutOptions.h | 50 ++++++++++++++++++-- AsyncDisplayKit/Layout/ASLayoutOptions.mm | 5 +- AsyncDisplayKit/Layout/ASLayoutSpec.mm | 2 +- AsyncDisplayKit/Layout/ASLayoutablePrivate.h | 8 ++++ AsyncDisplayKit/Layout/ASStackLayoutable.h | 3 ++ AsyncDisplayKit/Layout/ASStaticLayoutable.h | 3 ++ 6 files changed, 63 insertions(+), 8 deletions(-) diff --git a/AsyncDisplayKit/Layout/ASLayoutOptions.h b/AsyncDisplayKit/Layout/ASLayoutOptions.h index 15d2f1dd89..74352a34cf 100644 --- a/AsyncDisplayKit/Layout/ASLayoutOptions.h +++ b/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 +/** + * 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; -- (instancetype)initWithLayoutable:(id)layoutable; -- (void)setValuesFromLayoutable:(id)layoutable; - #pragma mark - Subclasses should implement these! -- (void)propagateOptionsFromLayoutOptions:(ASLayoutOptions *)layoutOptions; +/** + * 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)layoutable; + +/** + * 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 diff --git a/AsyncDisplayKit/Layout/ASLayoutOptions.mm b/AsyncDisplayKit/Layout/ASLayoutOptions.mm index b89b59ca85..67481cae02 100644 --- a/AsyncDisplayKit/Layout/ASLayoutOptions.mm +++ b/AsyncDisplayKit/Layout/ASLayoutOptions.mm @@ -86,11 +86,11 @@ static Class gDefaultLayoutOptionsClass = nil; - (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 @@ static Class gDefaultLayoutOptionsClass = nil; 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; diff --git a/AsyncDisplayKit/Layout/ASLayoutSpec.mm b/AsyncDisplayKit/Layout/ASLayoutSpec.mm index a91ca10372..46e56dff4a 100644 --- a/AsyncDisplayKit/Layout/ASLayoutSpec.mm +++ b/AsyncDisplayKit/Layout/ASLayoutSpec.mm @@ -82,7 +82,7 @@ static NSString * const kDefaultChildrenKey = @"kDefaultChildrenKey"; id finalLayoutable = [child finalLayoutable]; if (finalLayoutable != child) { - [finalLayoutable.layoutOptions propagateOptionsFromLayoutOptions:child.layoutOptions]; + [finalLayoutable.layoutOptions copyIntoOptions:child.layoutOptions]; return finalLayoutable; } } diff --git a/AsyncDisplayKit/Layout/ASLayoutablePrivate.h b/AsyncDisplayKit/Layout/ASLayoutablePrivate.h index a4aecf3a19..f52dd54ad6 100644 --- a/AsyncDisplayKit/Layout/ASLayoutablePrivate.h +++ b/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 /** @@ -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 diff --git a/AsyncDisplayKit/Layout/ASStackLayoutable.h b/AsyncDisplayKit/Layout/ASStackLayoutable.h index 5b1984929a..3ebc9304f0 100644 --- a/AsyncDisplayKit/Layout/ASStackLayoutable.h +++ b/AsyncDisplayKit/Layout/ASStackLayoutable.h @@ -11,6 +11,9 @@ #import #import +/** + * Layout options that can be defined for an ASLayoutable being added to a ASStackLayoutSpec. + */ @protocol ASStackLayoutable /** diff --git a/AsyncDisplayKit/Layout/ASStaticLayoutable.h b/AsyncDisplayKit/Layout/ASStaticLayoutable.h index f2e565a7a9..e0325cfc05 100644 --- a/AsyncDisplayKit/Layout/ASStaticLayoutable.h +++ b/AsyncDisplayKit/Layout/ASStaticLayoutable.h @@ -10,6 +10,9 @@ #import +/** + * Layout options that can be defined for an ASLayoutable being added to a ASStaticLayoutSpec. + */ @protocol ASStaticLayoutable /** From 3b4055fcd3fa194ed61bf2e0fcd763aa81566894 Mon Sep 17 00:00:00 2001 From: rcancro <@pinterest.com> Date: Tue, 15 Sep 2015 12:38:41 -0700 Subject: [PATCH 2/2] few more doc changes. --- AsyncDisplayKit/ASDisplayNode.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AsyncDisplayKit/ASDisplayNode.h b/AsyncDisplayKit/ASDisplayNode.h index f8a346bd9a..11a138ea4f 100644 --- a/AsyncDisplayKit/ASDisplayNode.h +++ b/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