Merge pull request #96 from Shopify/documentation-improvements

Added documentation to the init methods

FunctionalTableData.xcodeproj/project.pbxproj

@@ -148,14 +148,11 @@
 		17E57FE7208A404700BFCC3D /* FunctionalTableDataDemo */ = {
 			isa = PBXGroup;
 			children = (
-				17E57FFF208A425F00BFCC3D /* LabelCell.swift */,
 				17E57FE8208A404700BFCC3D /* AppDelegate.swift */,
-				17E57FEA208A404700BFCC3D /* TableExampleController.swift */,
-				17E57FEC208A404700BFCC3D /* CollectionExampleController.swift */,
-				17E57FEE208A404700BFCC3D /* Main.storyboard */,
-				17E57FF1208A404800BFCC3D /* Assets.xcassets */,
-				17E57FF3208A404800BFCC3D /* LaunchScreen.storyboard */,
 				17E57FF6208A404800BFCC3D /* Info.plist */,
+				4CCFDFF520B2230E00584343 /* Cells */,
+				4CCFDFF620B2231500584343 /* View Controllers */,
+				4CCFDFF420B2230200584343 /* Resources */,
 			);
 			path = FunctionalTableDataDemo;
 			sourceTree = "<group>";
@@ -254,6 +251,33 @@
 			path = TableView;
 			sourceTree = "<group>";
 		};
+		4CCFDFF420B2230200584343 /* Resources */ = {
+			isa = PBXGroup;
+			children = (
+				17E57FF1208A404800BFCC3D /* Assets.xcassets */,
+				17E57FF3208A404800BFCC3D /* LaunchScreen.storyboard */,
+				17E57FEE208A404700BFCC3D /* Main.storyboard */,
+			);
+			path = Resources;
+			sourceTree = "<group>";
+		};
+		4CCFDFF520B2230E00584343 /* Cells */ = {
+			isa = PBXGroup;
+			children = (
+				17E57FFF208A425F00BFCC3D /* LabelCell.swift */,
+			);
+			path = Cells;
+			sourceTree = "<group>";
+		};
+		4CCFDFF620B2231500584343 /* View Controllers */ = {
+			isa = PBXGroup;
+			children = (
+				17E57FEC208A404700BFCC3D /* CollectionExampleController.swift */,
+				17E57FEA208A404700BFCC3D /* TableExampleController.swift */,
+			);
+			path = "View Controllers";
+			sourceTree = "<group>";
+		};
 /* End PBXGroup section */
 
 /* Begin PBXHeadersBuildPhase section */

FunctionalTableData/CollectionView/FunctionalCollectionData.swift

@@ -48,9 +48,10 @@ public class FunctionalCollectionData: NSObject {
 	private let renderAndDiffQueue: OperationQueue
 	private let name: String
 
-	/// Index path for the previously selected row.
-	public var indexPathForPreviouslySelectedRow: IndexPath?
-
+	/// Enclosing `UICollectionView` that presents all the `TableSection` data.
+	///
+	/// `FunctionalCollectionData` will take care of setting its own `UICollectionViewDelegate` and
+	/// `UICollectionViewDataSource` and manage all the internals of the `UICollectionView` on its own.
 	public var collectionView: UICollectionView? {
 		didSet {
 			guard let collectionView = collectionView else { return }
@@ -63,15 +64,25 @@ public class FunctionalCollectionData: NSObject {
 		return sections[indexPath]
 	}
 
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619392-scrollviewdidscroll) for more information.
 	public var scrollViewDidScroll: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619394-scrollviewwillbegindragging) for more information.
 	public var scrollViewWillBeginDragging: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619385-scrollviewwillenddragging) for more information.
 	public var scrollViewWillEndDragging: ((_ scrollView: UIScrollView, _ velocity: CGPoint, _ targetContentOffset: UnsafeMutablePointer<CGPoint>) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619436-scrollviewdidenddragging) for more information.
 	public var scrollViewDidEndDragging: ((_ scrollView: UIScrollView, _ decelerate: Bool) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619386-scrollviewwillbegindecelerating) for more information.
 	public var scrollViewWillBeginDecelerating: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619417-scrollviewdidenddecelerating) for more information.
 	public var scrollViewDidEndDecelerating: ((_ scrollView: UIScrollView) -> Void)?
+	/// Tells the delegate that the scroll view has changed its content size.
 	public var scrollViewDidChangeContentSize: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619379-scrollviewdidendscrollinganimati) for more information.
 	public var scrollViewDidEndScrollingAnimation: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619378-scrollviewshouldscrolltotop) for more information.
 	public var scrollViewShouldScrollToTop: ((_ scrollView: UIScrollView) -> Bool)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619382-scrollviewdidscrolltotop) for more information.
 	public var scrollViewDidScrollToTop: ((_ scrollView: UIScrollView) -> Void)?
 
 	private let unitTesting: Bool
@@ -81,9 +92,12 @@ public class FunctionalCollectionData: NSObject {
 		return renderAndDiffQueue.isSuspended
 	}
 
-	public init(name: String? = nil, fileName: String = #file, lineNumber: Int = #line) {
-		self.unitTesting = NSClassFromString("XCTestCase") != nil
-		self.name = name ?? "FunctionalCollectionDataRenderAndDiff-\((fileName as NSString).lastPathComponent):\(lineNumber)"
+	/// Initializes a FunctionalCollectionData. To configure its view, provide a UICollectionView after initialization.
+	///
+	/// - Parameter name: String identifying this instance of FunctionalCollectionData, useful when several instances are displayed on the same screen. This also value names the queue doing all the rendering work, useful for debugging.
+	public init(name: String? = nil) {
+		self.name = name ?? "FunctionalCollectionDataRenderAndDiff"
+		unitTesting = NSClassFromString("XCTestCase") != nil
 		renderAndDiffQueue = OperationQueue()
 		renderAndDiffQueue.name = self.name
 		renderAndDiffQueue.maxConcurrentOperationCount = 1
@@ -369,7 +383,7 @@ public class FunctionalCollectionData: NSObject {
 	}
 
 	/// - Parameter point: The point in the collection view’s bounds that you want to test.
-	/// - Returns: the keypath of the item at the specified point, or `nil` if no item was found at that point.
+	/// - Returns: The keypath of the item at the specified point, or `nil` if no item was found at that point.
 	public func keyPath(at point: CGPoint) -> KeyPath? {
 		guard let indexPath = collectionView?.indexPathForItem(at: point) else {
 			return nil
@@ -378,6 +392,10 @@ public class FunctionalCollectionData: NSObject {
 		return keyPathForIndexPath(indexPath: indexPath)
 	}
 
+	/// Returns the IndexPath corresponding to the provided KeyPath.
+	///
+	/// - Parameter keyPath: The path representing the desired indexPath.
+	/// - Returns: The IndexPath of the item at the provided keyPath.
 	public func indexPathFromKeyPath(_ keyPath: KeyPath) -> IndexPath? {
 		if let sectionIndex = sections.index(where: { $0.key == keyPath.sectionKey }), let rowIndex = sections[sectionIndex].rows.index(where: { $0.key == keyPath.rowKey }) {
 			return IndexPath(item: rowIndex, section: sectionIndex)

FunctionalTableData/Separator.swift

@@ -44,10 +44,6 @@ public class Separator: UIView {
 		// numbers are random so subview tags don't conflict
 		case top = 2318
 		case bottom = 9773
-
-		var intValue: Int {
-			return self.rawValue
-		}
 	}
 
 	let style: Style

FunctionalTableData/TableView/FunctionalTableData.swift

@@ -84,17 +84,27 @@ public class FunctionalTableData: NSObject {
 		return sections[indexPath]
 	}
 
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619392-scrollviewdidscroll) for more information.
 	public var scrollViewDidScroll: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619394-scrollviewwillbegindragging) for more information.
 	public var scrollViewWillBeginDragging: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619385-scrollviewwillenddragging) for more information.
 	public var scrollViewWillEndDragging: ((_ scrollView: UIScrollView, _ velocity: CGPoint, _ targetContentOffset: UnsafeMutablePointer<CGPoint>) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619436-scrollviewdidenddragging) for more information.
 	public var scrollViewDidEndDragging: ((_ scrollView: UIScrollView, _ decelerate: Bool) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619386-scrollviewwillbegindecelerating) for more information.
 	public var scrollViewWillBeginDecelerating: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619417-scrollviewdidenddecelerating) for more information.
 	public var scrollViewDidEndDecelerating: ((_ scrollView: UIScrollView) -> Void)?
+	/// Tells the delegate that the scroll view has changed its content size.
 	public var scrollViewDidChangeContentSize: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619379-scrollviewdidendscrollinganimati) for more information.
 	public var scrollViewDidEndScrollingAnimation: ((_ scrollView: UIScrollView) -> Void)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619378-scrollviewshouldscrolltotop) for more information.
 	public var scrollViewShouldScrollToTop: ((_ scrollView: UIScrollView) -> Bool)?
+	/// See UIScrollView's [documentation](https://developer.apple.com/documentation/uikit/uiscrollviewdelegate/1619382-scrollviewdidscrolltotop) for more information.
 	public var scrollViewDidScrollToTop: ((_ scrollView: UIScrollView) -> Void)?
-	
+
 	/// The type of animation when rows and sections are inserted or deleted.
 	public struct TableAnimations {
 		public struct Actions {
@@ -128,9 +138,12 @@ public class FunctionalTableData: NSObject {
 		return renderAndDiffQueue.isSuspended
 	}
 
-	public init(name: String? = nil, fileName: String = #file, lineNumber: Int = #line) {
-		self.unitTesting = NSClassFromString("XCTestCase") != nil
-		self.name = name ?? "FunctionalTableDataRenderAndDiff-\((fileName as NSString).lastPathComponent):\(lineNumber)"
+	/// Initializes a FunctionalTableData. To configure its view, provide a UITableView after initialization.
+	///
+	/// - Parameter name: String identifying this instance of FunctionalTableData, useful when several instances are displayed on the same screen. This value also names the queue doing all the rendering work, useful for debugging.
+	public init(name: String? = nil) {
+		self.name = name ?? "FunctionalTableDataRenderAndDiff"
+		unitTesting = NSClassFromString("XCTestCase") != nil
 		renderAndDiffQueue = OperationQueue()
 		renderAndDiffQueue.name = self.name
 		renderAndDiffQueue.maxConcurrentOperationCount = 1