Polish animation documentation

CoconutKit/Sources/Animation/HLSAnimation.h

@@ -40,12 +40,7 @@
  * Animations can be played animated or not (yeah, that sounds weird, but I called it that way :-) ). When played
  * non-animated, an animation reaches its end state instantaneously. This is a perfect way to replay an animation
  * when rebuilding a view which has been unloaded (typically after a view controller received a memory warning 
- * notification on iOS 4 & 5. Views are not unloaded anymore since iOS 6)
- *
- * HLSAnimation does not provide any safety measures against non-integral frames (which ultimately lead to blurry
- * views). The reason is that fixing such issues in an automatic way would make reverse animations difficult to
- * generate, since HLSAnimation does not store any information about the original state of the views which are 
- * animated.
+ * notification on iOS 4 & 5. Note that views are not unloaded anymore since iOS 6)
  *
  * Running animations (this includes animations which have been paused) are automatically paused and resumed (if they
  * were running before) when the application enters, respectively exits background. Note that this mechanism works 
@@ -94,10 +89,10 @@
 
 /**
  * Create an animation using HLSAnimationStep objects. Those steps will be chained together when the animation
- * is played. If nil is provided, an empty animation is created (such animations still fire animationWillStart:animated: 
- * and animationDidStop:animated: events when played)
+ * is played. If nil is provided, an empty animation is created (such animations still fire -animationWillStart:animated:
+ * and -animationDidStop:animated: events when played)
  *
- * A deep copy of the animation steps is performed to prevent further changes once they have been assigned to an
+ * A deep copy of the animation steps is performed to prevent further changes once the steps have been assigned to an
  * animation
  */
 - (id)initWithAnimationSteps:(NSArray *)animationSteps;
@@ -114,7 +109,7 @@
 
 /**
  * If set to YES, the user interface interaction is blocked during the time the animation is running (see
- * the -running documentation for more information about what "running" means)
+ * the running property documentation for more information about what "running" actually means)
  *
  * Default is NO
  */

CoconutKit/Sources/Animation/HLSAnimation.m

@@ -19,6 +19,13 @@
 #import "NSArray+HLSExtensions.h"
 #import "NSString+HLSExtensions.h"
 
+/**
+ * HLSAnimation does not provide any safety measures against non-integral frames (which ultimately lead to blurry
+ * views). The reason is that fixing such issues in an automatic way would make reverse animations difficult to
+ * generate, since HLSAnimation does not store any information about the original state of the views which are
+ * animated.
+ */
+
 static NSString * const kDelayLayerAnimationTag = @"HLSDelayLayerAnimationStep";
 
 @interface HLSAnimation () <HLSAnimationStepDelegate>

CoconutKit/Sources/Animation/HLSAnimationStep+Friend.h

@@ -22,7 +22,7 @@
 - (void)playWithDelegate:(id<HLSAnimationStepDelegate>)delegate startTime:(NSTimeInterval)startTime animated:(BOOL)animated;
 
 /**
- * Pause the an animation step being played animated (does nothing if the animation is not running or not animated)
+ * Pause the animation step being played (does nothing if the animation is not running or not animated)
  */
 - (void)pause;
 
@@ -38,7 +38,7 @@
 
 /**
  * The time elapsed since the animation step began animating (might be self.duration if the animation step does 
- * not support arbitrary start times). This method must return the actual running time, removing pauses (if any)
+ * not support arbitrary start times). This method returns the actual running time, removing pauses (if any)
  */
 - (NSTimeInterval)elapsedTime;
 
@@ -54,15 +54,12 @@
 
 @end
 
-/**
- * The animated info which is returned is the same given when the play method was called (even if the animation
- * was actually not animated because its duration was 0)
- */
 @protocol HLSAnimationStepDelegate <NSObject>
 
 /**
  * Called when an animation step did stop. The finished boolean is YES iff the animation played until the end
- * without being terminated
+ * without being terminated. The animated info which is returned is the same given when the play method was 
+ * called (even if the animation was actually not animated because its duration was 0)
  */
 - (void)animationStepDidStop:(HLSAnimationStep *)animationStep animated:(BOOL)animated finished:(BOOL)finished;
 

CoconutKit/Sources/Animation/HLSAnimationStep+Protected.h

@@ -15,14 +15,14 @@
 @interface HLSAnimationStep (Protected)
 
 /**
- * Setting an animation for an object
+ * Set an animation for an object
  *
  * The object animation is deeply copied to prevent further changes once assigned to a step
  */
 - (void)addObjectAnimation:(HLSObjectAnimation *)objectAnimation forObject:(id)object;
 
 /**
- * Retrieving the animation for an object (nil if not match is found)
+ * Retrieve the animation for an object (nil if not match is found)
  */
 - (HLSObjectAnimation *)objectAnimationForObject:(id)object;
 

CoconutKit/Sources/Animation/HLSLayerAnimation+Friend.h

@@ -6,6 +6,10 @@
 //  Copyright (c) 2012 Hortis. All rights reserved.
 //
 
+/**
+  * Interface meant to be used by friend classes of HLSLayerAnimation (= classes which must have access to private implementation
+  * details)
+  */
 @interface HLSLayerAnimation (Friend)
 
 /**

CoconutKit/Sources/Animation/HLSLayerAnimation.h

@@ -20,11 +20,10 @@
  * A layer animation animates layer transforms, not frames. This choice was made because frame animation would 
  * restrict transforms to affine transforms, for which HLSViewAnimation can be used instead (provided the layer 
  * belongs to a view, of course). Moreover, unlike views, layers do not layout their sublayers automatically based 
- * on autoresizing properties on iOS (the -[CALayer layoutSublayers] or -[UIView layoutSublayersOfLayer:] methods
- * have to be implemented to respond to frame changes)
+ * on autoresizing properties on iOS
  *
  * Since the layer transform is animated, none of the -[CALayer layoutSublayers] or -[UIView layoutSublayersOfLayer:] 
- * methods need to be implemented for layers which are animated.
+ * methods need to be implemented for HLSLayerAnimation-based animations.
  *
  * In general, and if you do not need to animate view frames to resize subviews during animations, you should
  * use layer animations instead of view animations since they have far more capabilities.
@@ -70,8 +69,7 @@
 - (void)translateAnchorPointByVectorWithX:(CGFloat)x y:(CGFloat)y;
 
 /**
- * Geometric transform parameters to be applied to sublayers during the layer animation. In particular, tweaking the
- * skew parameter enables perspective to be applied to subviews, adding 3D to your animations
+ * Geometric transform parameters to be applied to sublayers during the layer animation
  */
 - (void)rotateSublayersByAngle:(CGFloat)angle aboutVectorWithX:(CGFloat)x y:(CGFloat)y z:(CGFloat)z;
 - (void)scaleSublayersWithXFactor:(CGFloat)xFactor yFactor:(CGFloat)yFactor zFactor:(CGFloat)zFactor;
@@ -80,8 +78,8 @@
 /**
  * Move the position of the camera from which sublayers are seen. The usual position is (0, 0, 0), which
  * means no perspective is applied (the sublayers are seen from infinity, i.e. z = infinity). Providing 
- * a non-zero meaningful value for z (usually some factor of the layer dimensions) applies a 3D perspective 
- * to sublayers
+ * a non-zero meaningful value for z (usually some factor of the layer or screen dimensions) applies a 
+ * 3D perspective to sublayers
  */
 - (void)translateSublayerCameraByVectorWithZ:(CGFloat)z;
 

CoconutKit/Sources/Animation/HLSObjectAnimation+Friend.h

@@ -6,6 +6,10 @@
 //  Copyright (c) 2012 Hortis. All rights reserved.
 //
 
+/**
+ * Interface meant to be used by friend classes of HLSObjectAnimation (= classes which must have access to private implementation
+ * details)
+ */
 @interface HLSObjectAnimation (Friend)
 
 /**

CoconutKit/Sources/Animation/HLSObjectAnimation.h

@@ -6,6 +6,9 @@
 //  Copyright (c) 2012 Hortis. All rights reserved.
 //
 
+/**
+ * Common abstract class for animations
+ */
 @interface HLSObjectAnimation : NSObject <NSCopying>
 
 /**

CoconutKit/Sources/Animation/HLSViewAnimation+Friend.h

@@ -6,6 +6,10 @@
 //  Copyright (c) 2012 Hortis. All rights reserved.
 //
 
+/**
+ * Interface meant to be used by friend classes of HLSViewAnimation (= classes which must have access to private implementation
+ * details)
+ */
 @interface HLSViewAnimation (Friend)
 
 /**

CoconutKit/Sources/Animation/HLSViewAnimation.h

@@ -36,8 +36,8 @@
 }
 
 /**
- * Geometric transform parameters to be applied during the view animation. The resulting transform (which you can 
- * obtain by calling -transform) applies the scale, then the translation
+ * Geometric transform parameters to be applied during the view animation. The resulting transform applies the scale, 
+ * then the translation
  */
 - (void)scaleWithXFactor:(CGFloat)xFactor yFactor:(CGFloat)yFactor;
 - (void)translateByVectorWithX:(CGFloat)x y:(CGFloat)y;