Merge pull request #62 from wwt/doc-enhancements

Enhances clarity of sample code and install.

wiki/Getting-Started-UIKit.md

@@ -2,29 +2,46 @@
 
 This guide will walk you through getting a [Workflow](https://wwt.github.io/SwiftCurrent/Classes/Workflow.html) up and running in a new iOS project.  If you would like to see an existing project, clone the repo and view the `SwiftCurrentExample` scheme in `SwiftCurrent.xcworkspace`.
 
+The app in this guide is going to be very simple.  It consists of a screen that will launch the [Workflow](https://wwt.github.io/SwiftCurrent/Classes/Workflow.html), a screen to enter an email address, and an optional screen for if your email contains `wwt.com`.  Here is a preview of what the app will look like:
+
+![Preview image of app](https://github.com/wwt/SwiftCurrent/wiki/programmatic.gif)
+
 ## Adding the dependency
 
 For instructions on SPM and CocoaPods, [check out our installation page.](https://github.com/wwt/SwiftCurrent/wiki/Installation#swift-package-manager)
 
+## IMPORTANT NOTE
+
+SwiftCurrent is so convenient that you may miss the couple lines that are calls to the library.  To make it easier, we've marked our code snippets with `// SwiftCurrent` to highlight items that are coming from the library.
+
 ## Create your view controllers
 
-Create two view controllers that inherit from [UIWorkflowItem<I, O>](https://wwt.github.io/SwiftCurrent/Classes/UIWorkflowItem.html).
+Create two view controllers that inherit from [UIWorkflowItem<I, O>](https://wwt.github.io/SwiftCurrent/Classes/UIWorkflowItem.html) and implement [FlowRepresentable](https://wwt.github.io/SwiftCurrent/Protocols/FlowRepresentable.html).
 
 ```swift
 import UIKit
 import SwiftCurrent
 import SwiftCurrent_UIKit
 
-class FirstViewController: UIWorkflowItem<String, String>, FlowRepresentable {
+class FirstViewController: UIWorkflowItem<String, String>, FlowRepresentable { // SwiftCurrent
     private let name: String
     private let emailTextField = UITextField()
     private let welcomeLabel = UILabel()
     private let saveButton = UIButton()
 
-    required init(with name: String) {
+    required init(with name: String) { // SwiftCurrent
         self.name = name
         super.init(nibName: nil, bundle: nil)
+        configureViews()
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    @objc private func savePressed() {
+        proceedInWorkflow(emailTextField.text ?? "") // SwiftCurrent
+    }
 
+    private func configureViews() {
         view.backgroundColor = .systemGray5
 
         welcomeLabel.text = "Welcome \(name)!"
@@ -54,23 +71,30 @@ class FirstViewController: UIWorkflowItem<String, String>, FlowRepresentable {
         saveButton.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
         saveButton.topAnchor.constraint(equalTo: emailTextField.bottomAnchor, constant: 24).isActive = true
     }
-
-    required init?(coder: NSCoder) { nil }
-
-    @objc private func savePressed() {
-        proceedInWorkflow(emailTextField.text ?? "")
-    }
 }
 
 // This screen shows an employee only screen
-class SecondViewController: UIWorkflowItem<String, String>, FlowRepresentable {
+class SecondViewController: UIWorkflowItem<String, String>, FlowRepresentable { // SwiftCurrent
     private let email: String
     private let finishButton = UIButton()
 
-    required init(with email: String) {
+    required init(with email: String) { // SwiftCurrent
         self.email = email
         super.init(nibName: nil, bundle: nil)
+        configureViews()
+    }
 
+    required init?(coder: NSCoder) { nil }
+
+    func shouldLoad() -> Bool { // SwiftCurrent
+        return email.contains("@wwt.com")
+    }
+
+    @objc private func finishPressed() {
+        proceedInWorkflow(email) // SwiftCurrent
+    }
+
+    private func configureViews() {
         view.backgroundColor = .systemGray5
 
         finishButton.setTitle("Finish", for: .normal)
@@ -84,16 +108,6 @@ class SecondViewController: UIWorkflowItem<String, String>, FlowRepresentable {
         finishButton.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
         finishButton.centerYAnchor.constraint(equalTo: view.centerYAnchor).isActive = true
     }
-
-    required init?(coder: NSCoder) { nil }
-
-    func shouldLoad() -> Bool {
-        return email.contains("@wwt.com")
-    }
-
-    @objc private func finishPressed() {
-        proceedInWorkflow(email)
-    }
 }
 ```
 
@@ -131,10 +145,10 @@ class ViewController: UIViewController {
     }
 
     @objc private func didTapLaunchWorkflow() {
-        let workflow = Workflow(FirstViewController.self)
-            .thenPresent(SecondViewController.self)
+        let workflow = Workflow(FirstViewController.self) // SwiftCurrent
+            .thenPresent(SecondViewController.self) // SwiftCurrent
 
-        launchInto(workflow, args: "Noble Six") { passedArgs in
+        launchInto(workflow, args: "Noble Six") { passedArgs in // SwiftCurrent
             workflow.abandon()
 
             guard case .args(let emailAddress as String) = passedArgs else {

wiki/Getting-Started.md

@@ -2,10 +2,18 @@
 
 This guide will walk you through getting a [Workflow](https://wwt.github.io/SwiftCurrent/Classes/Workflow.html) up and running in a new iOS project.  If you would like to see an existing project, clone the repo and view the `SwiftCurrentExample` scheme in `SwiftCurrent.xcworkspace`.
 
+The app in this guide is going to be very simple.  It consists of a screen that will launch the [Workflow](https://wwt.github.io/SwiftCurrent/Classes/Workflow.html), a screen to enter an email address, and an optional screen for if your email contains `wwt.com`.  Here is a preview of what the app will look like:
+
+![Preview image of app](https://github.com/wwt/SwiftCurrent/wiki/storyboard.gif)
+
 ## Adding the dependency
 
 For instructions on SPM and CocoaPods, [check out our installation page.](https://github.com/wwt/SwiftCurrent/wiki/Installation#swift-package-manager)
 
+## IMPORTANT NOTE
+
+SwiftCurrent is so convenient that you may miss the couple lines that are calls to the library.  To make it easier, we've marked our code snippets with `// SwiftCurrent` to highlight items that are coming from the library.
+
 ## Create the convenience protocols for storyboard loading
 
 It is best practice to use the [StoryboardLoadable](https://wwt.github.io/SwiftCurrent/Protocols/StoryboardLoadable.html) protocol to connect your [FlowRepresentable](https://wwt.github.io/SwiftCurrent/Protocols/FlowRepresentable.html) to your Storyboard.  Additionally, to limit the amount of duplicate code, you can make a convenience protocol for each storyboard.
@@ -14,7 +22,8 @@ It is best practice to use the [StoryboardLoadable](https://wwt.github.io/SwiftC
 import UIKit
 import SwiftCurrent_UIKit
 
-extension StoryboardLoadable {
+extension StoryboardLoadable { // SwiftCurrent
+    // Assumes that your storyboardId will be the same as your UIViewController class name
     static var storyboardId: String { String(describing: Self.self) }
 }
 
@@ -34,7 +43,7 @@ Create two view controllers that both conform to `MainStoryboardLoadable` and in
 import UIKit
 import SwiftCurrent_UIKit
 
-class FirstViewController: UIWorkflowItem<String, String>, MainStoryboardLoadable {
+class FirstViewController: UIWorkflowItem<String, String>, MainStoryboardLoadable { // SwiftCurrent
     private let name: String
 
     @IBOutlet private weak var emailTextField: UITextField!
@@ -44,33 +53,33 @@ class FirstViewController: UIWorkflowItem<String, String>, MainStoryboardLoadabl
         }
     }
 
-    required init?(coder: NSCoder, with name: String) {
+    required init?(coder: NSCoder, with name: String) { // SwiftCurrent
         self.name = name
         super.init(coder: coder)
     }
 
     required init?(coder: NSCoder) { nil }
 
     @IBAction private func savePressed(_ sender: Any) {
-        proceedInWorkflow(emailTextField.text ?? "")
+        proceedInWorkflow(emailTextField.text ?? "") // SwiftCurrent
     }
 }
 
 // This screen shows an employee only screen
-class SecondViewController: UIWorkflowItem<String, String>, MainStoryboardLoadable {
+class SecondViewController: UIWorkflowItem<String, String>, MainStoryboardLoadable { // SwiftCurrent
     private let email: String
-    required init?(coder: NSCoder, with email: String) {
+    required init?(coder: NSCoder, with email: String) { // SwiftCurrent
         self.email = email
         super.init(coder: coder)
     }
 
     required init?(coder: NSCoder) { nil }
 
     @IBAction private func finishPressed(_ sender: Any) {
-        proceedInWorkflow(email)
+        proceedInWorkflow(email) // SwiftCurrent
     }
 
-    func shouldLoad() -> Bool {
+    func shouldLoad() -> Bool { // SwiftCurrent
         return email.contains("@wwt.com")
     }
 }
@@ -121,9 +130,10 @@ import SwiftCurrent_UIKit
 
 class ViewController: UIViewController {
     @IBAction private func launchWorkflow() {
-        let workflow = Workflow(FirstViewController.self)
-                            .thenPresent(SecondViewController.self)
-        launchInto(workflow, args: "Some Name") { passedArgs in
+        let workflow = Workflow(FirstViewController.self) // SwiftCurrent
+                            .thenPresent(SecondViewController.self) // SwiftCurrent
+
+        launchInto(workflow, args: "Some Name") { passedArgs in // SwiftCurrent
             workflow.abandon()
             guard case .args(let emailAddress as String) = passedArgs else {
                 print("No email address supplied")
@@ -172,6 +182,7 @@ import XCTest
 import UIUTest
 import SwiftCurrent
 
+// This assumes your project was called GettingStarted.
 @testable import GettingStarted
 
 class SecondViewControllerTests: XCTestCase {

wiki/Installation.md

@@ -12,18 +12,16 @@ Add the following line to the package dependencies
 .package(url: "https://github.com/wwt/SwiftCurrent.git", .upToNextMajor(from: "4.0.0")),
 ```
 
-## Get the correct product
+## Get the products
 
 Add the following products to your target dependencies.
 
-#### **If you want to use SwiftCurrent with UIKit**
-
 ```swift
 .product(name: "SwiftCurrent", package: "SwiftCurrent"),
 .product(name: "SwiftCurrent_UIKit", package: "SwiftCurrent")
 ```
 
-#### **Your import statements for these products will be**
+### Your import statements for these products will be
 
 ```swift
 import SwiftCurrent
@@ -37,13 +35,13 @@ import SwiftCurrent_UIKit
 
 Set up [CocoaPods](https://cocoapods.org/) for your project, then include SwiftCurrent in your dependencies by adding the following line to your `Podfile`:
 
-#### **If you want to use SwiftCurrent with UIKit**
+### To use SwiftCurrent with UIKit
 
 ```ruby
 pod 'SwiftCurrent/UIKit'
 ```
 
-#### **Your import statement will be**
+### Your import statement will be
 
 ```swift
 import SwiftCurrent