Still working on doc, adding rows

Author: malcommac

README.md

@@ -15,6 +15,8 @@ You can think of it as `UITableView` but with several differences:
 - Main Features
 - System Requirements
 - How to use it
+	- Adding Rows
+	- Removing Rows
 
 ### Main Features
 
@@ -36,3 +38,62 @@ You can think of it as `UITableView` but with several differences:
 - Swift 5+
 
 ### How to use it
+
+The main class of the package is `ScrollStack`, a subclass of `UIScrollView`. It manages the layout of each row, animations and keep a strong reference to your rows.
+
+However usually you don't want to intantiate this control directly but by calling the `ScrollStackController` class.
+It's a view controller which allows you to get the child view controller's managment for free, so when you add/remove a row to the stack you will get the standard UIViewController events for free!
+
+This is an example of initialization in a view controller:
+
+```swift
+class MyViewController: UIViewController {
+
+    private var stackController = ScrollStackViewController()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        contentView.addSubview(stackController.view)
+    }
+    
+}
+```
+
+Now you are ready to use the `ScrollStack` control inside the `stackController` class.
+`ScrollStack` have an extensible rich set of APIs to manage your layout: add, remove, move, hide or show your rows, including insets and separator management.
+
+Each row managed by `ScrollStack` is a subclass of `ScrollStackRow`: it strongly reference a parent `UIViewController` class where you content is placed. `UIViewController`'s `view` will be the `contentView` of the row.
+
+You don't need to handle lifecycle of your rows/view controller until they are part of the rows inside the stack.
+
+Let's take a look below.
+
+#### Adding Rows
+
+`ScrollStack` provides a comprehensive set of methods for managing rows, including inserting rows at the beginning and end, inserting rows above or below other rows.
+
+To add row you can use one the following methods:
+
+- `addRow(controller:at:animated:) -> ScrollStackRow?`
+- `addRows(controllers:at:animated:) -> [ScrollStackRow]?`
+
+Both of these methods takes as arguments:
+
+- `controller/s`: one or more `UIViewController` instances; each view of these controllers will be as a row of the stack inside a `ScrollStackRow` (a sort of cell).
+- `at`: specify the insertion point. It's an enum with the following options: `top` (at first index), `bottom` (append at the bottom of the list), `atIndex` (specific index), `after` or `below` (after/below a row which contain a specific `UIViewController`).
+- `animated`: if true insertion will be animated
+- `completion`: completion callback to call at the end of the operation.
+
+The following code add a rows with the view of each view controller passed:
+
+```swift
+   let welcomeVC = WelcomeVC.create()
+   let tagsVC = TagsVC.create(delegate: self)
+   let galleryVC = GalleryVC.create()
+        
+   stackView.addRows(controllers: [welcomeVC, notesVC, tagsVC, galleryVC], animated: false)
+```
+
+As you noted there is not need to keep a strong reference to any view controller; they are automatically strong referenced by each row created to add them into the stack.
+
+#### Removing Rows

ScrollStackController.xcodeproj/project.xcworkspace/xcuserdata/daniele.xcuserdatad/UserInterfaceState.xcuserstate

@@ -207,37 +207,38 @@ open class ScrollStack: UIScrollView, UIScrollViewDelegate {
     }
 
     // MARK: - Insert Rows
-    
     /// Insert a new row to manage passed controller instance.
     ///
     /// - Parameter controller: controller to manage; it's `view` will be added as contentView of the row.
     /// - Parameter location: location inside the stack of the new row.
     /// - Parameter animated: `true` to animate operation, by default is `false`.
+    /// - Parameter completion: optional completion callback to call at the end of insertion.
     @discardableResult
-    open func addRow(controller: UIViewController, at location: InsertLocation = .bottom, animated: Bool = false) -> ScrollStackRow? {
+    open func addRow(controller: UIViewController, at location: InsertLocation = .bottom, animated: Bool = false, completion: (() -> Void)? = nil) -> ScrollStackRow? {
         switch location {
         case .top:
-            return createRowForController(controller, insertAt: 0, animated: animated)
+            return createRowForController(controller, insertAt: 0, animated: animated, completion: completion)
 
         case .bottom:
-            return createRowForController(controller, insertAt: rows.count, animated: animated)
+            return createRowForController(controller, insertAt: rows.count, animated: animated, completion: completion)
 
         case .atIndex(let index):
-            return createRowForController(controller, insertAt: index, animated: animated)
+            return createRowForController(controller, insertAt: index, animated: animated, completion: completion)
 
         case .after(let afterController):
             guard let index = rowForController(afterController)?.index else {
                 return nil
             }
 
-            return createRowForController(controller, insertAt: ((index + 1) >= rows.count ? rows.count : (index + 1)), animated: animated)
+            let finalIndex = ((index + 1) >= rows.count ? rows.count : (index + 1))
+            return createRowForController(controller, insertAt: finalIndex, animated: animated, completion: completion)
 
         case .before(let beforeController):
             guard let index = rowForController(beforeController)?.index else {
                 return nil
             }
 
-            return createRowForController(controller, insertAt: index, animated: animated)
+            return createRowForController(controller, insertAt: index, animated: animated, completion: completion)
 
         }
     }