Adding code header and documentation

TimOliver · TimOliver · commit 49e2202b011c · 2017-08-11T16:34:55.000+08:00
diff --git a/TOPasscodeViewController/Models/TOPasscodeCircleImage.h b/TOPasscodeViewController/Models/TOPasscodeCircleImage.h
@@ -1,18 +1,55 @@
 //
-//  TOPasscodeImage.h
-//  TOPasscodeViewControllerExample
+//  TOPasscodeCircleImage.h
 //
-//  Created by Tim Oliver on 5/17/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A subclass of `UIImage` that can procedurally generate both hollow and full circle graphics at any size.
+ These are used for the 'normal' and 'tapped' states of the passcode circle buttons.
+ */
 @interface TOPasscodeCircleImage : UIImage
 
+/**
+ Generates and returns a `UIImage` of a filled circle at the specified size.
+
+ @param size     The diameter of the final circle image
+ @param inset    An inset value that will shrink the size of the circle. This is so it can be overlaid on a hollow circle
+                    without interfering with the anti-aliasing on the outer border.
+ @param padding  External padding around the circle to ensure it won't be clipped by the edge of the layer.
+                    Setting this value will increase the dimensions of the final `UIImage`.
+ @param antialias Whether the circle boundary will be antialiased (Since antialiasing is unnecessary if this circle will overlay another.)
+ */
 + (UIImage *)circleImageOfSize:(CGFloat)size inset:(CGFloat)inset padding:(CGFloat)padding antialias:(BOOL)antialias;
+
+/**
+ Generates and returns a `UIImage` of a hollow circle at the specified size.
+
+ @param size        The diameter of the final circle image
+ @param strokeWidth The thickness, in points, of the stroke making up the circle image.
+ @param padding     External padding around the circle to ensure it won't be clipped by the edge of the layer.
+                      Setting this value will increase the dimensions of the final `UIImage`.
+ */
 + (UIImage *)hollowCircleImageOfSize:(CGFloat)size strokeWidth:(CGFloat)strokeWidth padding:(CGFloat)padding;
 
 @end
diff --git a/TOPasscodeViewController/Models/TOPasscodeCircleImage.m b/TOPasscodeViewController/Models/TOPasscodeCircleImage.m
@@ -1,10 +1,24 @@
 //
-//  TOPasscodeImage.m
-//  TOPasscodeViewControllerExample
+//  TOPasscodeCircleImage.m
 //
-//  Created by Tim Oliver on 5/17/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import "TOPasscodeCircleImage.h"
 
diff --git a/TOPasscodeViewController/Models/TOPasscodeViewContentLayout.h b/TOPasscodeViewController/Models/TOPasscodeViewContentLayout.h
@@ -1,14 +1,45 @@
 //
-//  TOPasscodeViewContentConfiguration.h
-//  TOPasscodeViewControllerExample
+//  TOPasscodeViewContentLayout.h
 //
-//  Created by Tim Oliver on 5/19/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import <Foundation/Foundation.h>
 #import <UIKit/UIKit.h>
 
+/**
+ Depending on the width of the application window, all of the content views in
+ the passcode view need to be resized in order to fit in the available space.
+
+ This means that not only does the spacing and sizing of views need to be changed, but
+ image assets need to be regenerated and font sizes need to change as well.
+
+ This class assumes there will be three major screen sizes, and provides layout
+ sizes, spacing, and styles in order to resize the passcode view for each one.
+
+ The three screen styles it supports are:
+
+ * Small Screens - iPhone 5/ or iPad 9.7" in 1/4 split screen mode
+ * Medium Screens - iPhone 6/ or iPad 12.9" in 1/4 split screen mode
+ * Large Screens - iPhone 6 Plus and all iPads when not in split screen mode.
+
+ */
 @interface TOPasscodeViewContentLayout : NSObject
 
 /* The width of the PIN view in which this layout object is sizing the content to fit. */
diff --git a/TOPasscodeViewController/Models/TOPasscodeViewContentLayout.m b/TOPasscodeViewController/Models/TOPasscodeViewContentLayout.m
@@ -1,10 +1,24 @@
 //
-//  TOPasscodeViewContentConfiguration.m
-//  TOPasscodeViewControllerExample
+//  TOPasscodeViewContentLayout.m
 //
-//  Created by Tim Oliver on 5/19/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import "TOPasscodeViewContentLayout.h"
 
diff --git a/TOPasscodeViewController/Models/TOPasscodeViewControllerAnimatedTransitioning.h b/TOPasscodeViewController/Models/TOPasscodeViewControllerAnimatedTransitioning.h
@@ -13,13 +13,33 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ An class conforming to `UIViewControllerAnimatedTransitioning` that handles the custom animation
+ that plays when the passcode view controller is presented on the user's screen.
+ */
 @interface TOPasscodeViewControllerAnimatedTransitioning : NSObject <UIViewControllerAnimatedTransitioning>
 
+/** The parent passcode view controller that this object will be controlling */
 @property (nonatomic, weak, readonly) TOPasscodeViewController *passcodeViewController;
+
+/** Whether the controller is being presented or dismissed. The animation is played in reverse when dismissing. */
 @property (nonatomic, assign) BOOL dismissing;
-@property (nonatomic, assign) BOOL passcodeSuccess; //Play a different animation if the password succeeeded
 
-- (instancetype)initWithPasscodeViewController:(TOPasscodeViewController *)passcodeViewController dismissing:(BOOL)dismissing success:(BOOL)success;
+/** If the correct passcode was successfully entered, this property can be set to YES. When the view controller
+ is dismissing, the keypad view will also play a zooming out animation to give added context to the dismissal. */
+@property (nonatomic, assign) BOOL success;
+
+/**
+ Creates a new instanc of `TOPasscodeViewControllerAnimatedTransitioning` that will control the provided passcode
+ view controller.
+
+ @param passcodeViewController The passcode view controller in which this object will coordinate the animation upon.
+ @param dismissing Whether the animation is played to present the view controller, or dismiss it.
+ @param success Whether the object needs to play an additional zooming animation denoting the passcode was successfully entered.
+ */
+- (instancetype)initWithPasscodeViewController:(TOPasscodeViewController *)passcodeViewController
+                                    dismissing:(BOOL)dismissing
+                                       success:(BOOL)success;
 
 @end
 
diff --git a/TOPasscodeViewController/Models/TOPasscodeViewControllerAnimatedTransitioning.m b/TOPasscodeViewController/Models/TOPasscodeViewControllerAnimatedTransitioning.m
@@ -21,7 +21,7 @@ - (instancetype)initWithPasscodeViewController:(TOPasscodeViewController *)passc
     if (self = [super init]) {
         _passcodeViewController = passcodeViewController;
         _dismissing = dismissing;
-        _passcodeSuccess = success;
+        _success = success;
     }
 
     return self;
diff --git a/TOPasscodeViewController/Models/TOSettingsKeypadImage.h b/TOPasscodeViewController/Models/TOSettingsKeypadImage.h
@@ -1,22 +1,52 @@
 //
 //  TOSettingsKeypadImage.h
-//  TOPasscodeViewControllerExample
 //
-//  Created by Tim Oliver on 6/20/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A subclass of `UIImage` that procedurally generates images for `TOPasscodeSettingsKeypadView`.
+ This includes background images for each keypad button, and a delete icon for the bottom right corner
+ of the keypad.
+ */
 @interface TOSettingsKeypadImage : UIImage
 
+/**
+ Generates and returns an image of button background with a raised border in a pseudo-skeuomorphic style.
+
+ @param radius The rounded radius of the button image's corners
+ @param foregroundColor The fill color of the primary section of the button
+ @param edgeColor The color of the raised border edge along the bottom.
+ @param thickness The size of the border running along the bottom
+ */
 + (UIImage *)buttonImageWithCornerRadius:(CGFloat)radius
                          foregroundColor:(UIColor *)foregroundColor
                                edgeColor:(UIColor *)edgeColor
                            edgeThickness:(CGFloat)thickness;
 
+/**
+Generates and returns a tintable delete icon.
+ */
 + (UIImage *)deleteIcon;
 
 @end
diff --git a/TOPasscodeViewController/TOPasscodeSettingsViewController.h b/TOPasscodeViewController/TOPasscodeSettingsViewController.h
@@ -1,10 +1,24 @@
 //
 //  TOPasscodeSettingsViewController.h
-//  TOPasscodeViewControllerExample
 //
-//  Created by Tim Oliver on 6/8/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import <UIKit/UIKit.h>
 #import "TOPasscodeViewControllerConstants.h"
@@ -19,6 +33,9 @@ typedef NS_ENUM(NSInteger, TOPasscodeSettingsViewState) {
 
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ A delegate object in charge of validating and recording the passcodes entered by the user.
+ */
 @protocol TOPasscodeSettingsViewControllerDelegate <NSObject>
 
 @optional
@@ -40,6 +57,14 @@ NS_ASSUME_NONNULL_BEGIN
 
 // ----------------------------------------------------------------------
 
+/**
+ A standard system-styled view controller that users can use to change the passcode
+ that they will need to enter for the main passcode view controller.
+
+ This controller allows requiring the user to enter their previous passcode in first,
+ and has passcode validation by requiring them to enter the new passcode twice.
+ */
+
 @interface TOPasscodeSettingsViewController : UIViewController
 
 /** Delegate event for controlling and responding to the behavior of this controller */
diff --git a/TOPasscodeViewController/TOPasscodeSettingsViewController.m b/TOPasscodeViewController/TOPasscodeSettingsViewController.m
@@ -1,10 +1,24 @@
 //
 //  TOPasscodeSettingsViewController.m
-//  TOPasscodeViewControllerExample
 //
-//  Created by Tim Oliver on 6/8/17.
-//  Copyright © 2017 Timothy Oliver. All rights reserved.
+//  Copyright 2017 Timothy Oliver. All rights reserved.
 //
+//  Permission is hereby granted, free of charge, to any person obtaining a copy
+//  of this software and associated documentation files (the "Software"), to
+//  deal in the Software without restriction, including without limitation the
+//  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the Software is
+//  furnished to do so, subject to the following conditions:
+//
+//  The above copyright notice and this permission notice shall be included in
+//  all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+//  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+//  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #import "TOPasscodeSettingsViewController.h"
 #import "TOPasscodeInputField.h"
diff --git a/TOPasscodeViewController/TOPasscodeViewController.h b/TOPasscodeViewController/TOPasscodeViewController.h
diff --git a/TOPasscodeViewController/TOPasscodeViewController.m b/TOPasscodeViewController/TOPasscodeViewController.m

Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ - (instancetype)initWithPasscodeViewController:(TOPasscodeViewController *)passc`
`21`	`21`	`if (self = [super init]) {`
`22`	`22`	`_passcodeViewController = passcodeViewController;`
`23`	`23`	`_dismissing = dismissing;`
`24`		`- _passcodeSuccess = success;`
	`24`	`+ _success = success;`
`25`	`25`	`}`
`26`	`26`
`27`	`27`	`return self;`