Update readme and introduction.

Documentation/Installation.md

@@ -1,8 +1,18 @@
 #  Resolver: Installation
 
-## Not yet Implemented
+## CocoaPods
 
-The plan is for Resolver to be Carthage, Cocoapods, and Swift Framework compliant.
+Resolver is available through CocoaPods. To install it, simply add the following line to your Podfile:
+
+```
+pod "Resolver"
+```
+
+Special thanks to [Khoa Pham](https://github.com/onmyway133) for making the *Resolver* repo available on CocoaPods.
+
+### Carthage / Swift Frameworks
+
+The plan is for Resolver to be Carthage and Swift Framework compliant.
 
 That's the plan. For now, however, just checkout the project and add `Resolver.swift` to your project's Third Party Software folder.
 

Documentation/Introduction.md

@@ -54,50 +54,67 @@ Those two changes allow us to meet all of the goals mentioned above.
 
 Pass the right implementation of NetworkServicing to MyViewModel, and the data can be pulled from the network, from a cache, from a test file on disk, or from a pool of mocked data.
 
-## Containers
-
 Okay, fine. But doesn't this approach just kick the can further down the road?
 
-How does MyViewModel get the right version of NetworkServicing?
+How do I get MyViewModel and how does MyViewModel get the right version of NetworkServicing? Don't I have to create it and set it's property myself?
+
+Well, you could, but the better answer is to use Dependency Injection.
+
+## Registration
 
-Here, Resolver is being asked to register the type ABCService.
+Dependency Injection works in two phases: *Registration* and *Resolution*.
+
+Registration consists of registering the classes and objects we're going to need,  as well as providing a *factory* closure to create an instance of one when needed.
 
 ```
-Resolver.register { ABCService() }
+Resolver.register { NetworkService() as NetworkServicing }
+
+Resolver.register { MyViewModel() }.resolveProperties { (_, model) in
+    model.service = optional() // note NetworkServicing was defined as an ExplicitlyUnwrappedOptional
+}
 ```
-Note that a factory closure was provided that will create an instance of ABCService when needed.
+
+The above looks a bit complex, but it's actually fairly straightforward.
+
+First, we registered a factory (closure) that will create an instance of NetworkService when needed. The type being registered is [automatically inferred](Types.md) using the result type returned by the factory.
+
+Hence we're creating a NetworkService, but we're acutally registering the protocol NetworkServicing.
+
+Similarly, we registered a factory to create MyViewModel's when needed, and we also added a resolveProperties closure to [resolve](Resolving.md) its service property.
+
+## Resolution
 
 Once registered, any object can ask Resolver to provide (resolve) an object of that type.
 
 ```
-var abc: ABCService = Resolver.resolve()
+var viewModel: MyViewModel = Resolver.resolve()
 ```
 
 ## Why bother?
 
 So we registered a factory, and asked Resolver to resolve it, and it worked... but why go to the extra trouble?
 
-Why we don't just directly instantiate an ABCService and be done with it?
+Why we don't just directly instantiate  MyViewModel and be done with it?
 ```
-let abc = ABCService()
+var viewModel = MyViewModel()
+viewModel.service = NetworkService()
 ```
 Well, there are several reasons why this is a bad idea, but let's start with two:
 
-First, what happens if ABCService in turn requires other classes or objects to do its job? And what happens if those objects need references to other objects, services, and system resources?
+First, what happens if NetworkService in turn required other classes or objects to do its job? And what happens if those objects need references to other objects, services, and system resources?
 
 ```
-let session = XYZSession()
-let fetcher = JKLFetcher(session)
-let abc = ABCService(fetcher)
+var viewModel = MyViewModel()
+viewModel.service = NetworkService(TokenVendor.token(AppDelegate.seed))
 ```
 
 You're literally left with needing to construct the objects needed... to build the objects needed... to build the single instance of the object that you actually wanted in the first place.
 
 Those additonal objects are known as *dependencies*.
 
-Second, and worse, the constructing class now knows the internals and requirements for ABCService, and for JKLFetcher, and it also knows about XYZSession.
+Second, and worse, the constructing class now knows the internals and requirements for MyViewModel, and for NetworkService, and it also knows about TokenVendor and its requirements.
 
-It's now tightly *coupled* to the behavior and distinct implementations of all of those classes... when all it really wanted to do was talk to an ABCService.
+It's now tightly *coupled* to the behavior and distinct implementations of all of those classes... when all it really wanted to do was talk to a MyViewModel.
 
 ## ViewControllers, ViewModel, and Services. Oh, my.
 
@@ -126,62 +143,54 @@ class XYZViewModel {
         self.updater = updater
         self.service = service
     }
+    // Implmentation
 }
 
 class XYZCombinedService: XYZFetching, XYZUpdating {
-    // Implements protocols
-}
-
-struct XYZService {
     private var session: XYZSessionService
     init(_ session: XYZSessionService) {
         self.session = session
     }
+    // Implmentation
+}
+
+struct XYZService {
+    // Implmentation
 }
 
 class XYZSessionService {
     // Implmentation
 }
 ```
 
-Note that the initializers for XYZViewModel and XYZService are each passed the objects they need to do their jobs. To use Dependency Injection lingo, this is known as *Initialization Injection* and it's the recommended approach to object construction.
+Note that the initializers for XYZViewModel and XYZCombinedService are each passed the objects they need to do their jobs. To use Dependency Injection lingo, this is known as [Initialization or Constructor Injection](Injection.md#constructor) and it's the recommended approach to object construction.
 
 ## Registration
 
 Let's use Resolver to register these classes.
 
 Here we're extending the base Resolver class with the ResolverRegistering protcol, which pretty much just tells Resolver that we've added the registerAllServices() function.
 
-"registerAllServices" is automatically called by Resolver the first time it's asked to resolve a service, in effect performing a one-time initialization of the resolution system.
+The `registerAllServices` function is automatically called by Resolver the first time it's asked to resolve a service, in effect performing a one-time initialization of the resolution system.
 
 ```
 extension Resolver: ResolverRegistering {
-
     public static func registerAllServices() {
-
-        // Register instance with injected parameters
-        main.register { XYZViewModel(fetcher: resolve(), updater: resolve(), service: resolve()) }
-
-        // Register protocols XYZFetching and XYZUpdating
-        main.register { XYZCombinedService() as XYZFetching }
-        main.register { XYZCombinedService() as XYZUpdating }
-
-        // Register XYZService and return instance in factory closure
-        main.register { XYZService() }
-
-        // Register XYZSessionService and return instance in factory closure
-        main.register { XYZSessionService() }
-
+        register { XYZViewModel(fetcher: resolve(), updater: resolve(), service: resolve()) }
+        register { XYZCombinedService(resolve()) }
+            .implements(XYZFetching.self)
+            .implements(XYZUpdating.self)
+        register { XYZService() }
+        register { XYZSessionService() }
     }
-
 }
 ```
 
-So, the above code shows us registering XYZViewModel, the protocols XYZFetching and XYZUpdating, the XYZService, and the XYZSessionService.
+So, the above code shows us registering XYZViewModel, the protocols XYZFetching and XYZUpdating, the XYZCombinedService, the XYZService, and the XYZSessionService.
 
 [Learn more about Registration](Registration.md)
 
-## Resolving
+## Resolution
 
 Now we've registered all of the objects our app is going to use. But what starts the process? Who resolves first?
 
@@ -193,13 +202,64 @@ class MyViewController: UIViewController, Resolving {
 }
 ```
 
-Adopting the Resolving protocol injects the default resolver instance into MyViewController. Calling resolve on that instance allows it to request a XYZViewModel from Resolver.
+Adopting the Resolving protocol injects the default resolver instance into MyViewController (Interface Injection). Calling resolve on that instance allows it to request a XYZViewModel from Resolver.
 
-Resolver processes the request, returns the correct instance, and MyViewController gets its XYZViewModel.
+Resolver processes the request, finds the right factory to make a XYZViewModel, and tells it to do so. 
 
-It doesn't know the internals of XYZViewModel, nor does it know about XYZFetcher's, XYZUpdater's, XYZService's, or XYZSessionService's.
+The XYZViewModel factory, in turn, triggers the resolution of the types that *it* needs (XYZFetching, XYZUpdating, and XYZService), and so on, down the chain. Eventually, the XYZViewModel factory gets everything it needs, returns the correct instance, and MyViewController gets its view model.
+
+MyViewController doesn't know the internals of XYZViewModel, nor does it know about XYZFetcher's, XYZUpdater's, XYZService's, or XYZSessionService's.
 
 Nor does it need to. It simply asks Resolver for an instance of type T, and Resolver complies.
 
-[Learn more about Resolving](Resolving.md)
+Learn more about [Resolving](Resolving.md) and the [Resolution Cycle](Cycle.md).
+
+## Mocking
+
+Okay, you might think. That's pretty cool, but earlier you mentioned other benefits, like testing and mocking. What about those?
+
+Consider the following change to the above code:
+
+```
+extension Resolver {
+    static func registerAllServices() {
+        register { XYZViewModel(fetcher: resolve(), updater: resolve(), service: resolve()) }
+        register { XYZCombinedService(resolve()) }
+            .implements(XYZFetching.self)
+            .implements(XYZUpdating.self)
+        register { XYZService() }
+        register { XYZSessionService() }
+
+        #if DEBUG
+        register { XYZMockSessionService() as XYZSessionService }
+        #end
+    }
+}
+```
+
+This is just one approach, but it illustrates the concept. Now when MyViewController asks for a XYZViewModel, it gets one. The resolved XYZViewModel, in turn has its fetcher, updater, and service.
+
+However, if we're in debug mode the fetcher and updater now have a XYZMockSessionService, which pulls mock data from embedded files instead of going out to the server as normal.
+
+And both MyViewController and XYZViewModel are none the wiser.
+
+## Testing
+
+Same for unit testing. Add something like the following to the unit test code.
+
+```
+let data = ["name":"Mike", "developer":true]
+register { XYZTestSessionService(data) as XYZSessionService }
+let viewModel: XYZViewModel = Resolver.resolve()
+```
+
+Now your unit and integration tests for XYZViewModel as using XYZTestSessionService, which povides stable, known data to the model.
+
+Do it again.
+```
+let data = ["name":"Boss", "developer":false]
+register { XYZTestSessionService(data) as XYZSessionService }
+let viewModel: XYZViewModel = Resolver.resolve()
+```
 
+And you can now easily test different scenarios.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Michael Long
+Copyright (c) 2018 Michael Long
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -64,6 +64,17 @@ Further, Resolver:
 
 Finally, with  [Automatic Type Inference](https://github.com/hmlongco/Resolver/blob/master/Documentation/Types.md) you also tend to write about 40-60% less dependency injection code using Resolver.
 
+## Author
+
+Resolver was designed, implemented, and documented by [Michael Long](https://www.linkedin.com/in/hmlong/), a Senior Lead iOS engineer at [CRi Solutions](https://www.clientresourcesinc.com/solutions/). CRi is a leader in developing cutting edge iOS, Android, and mobile web applications and solutions for our corporate and financial clients.
+
+* Email: [[email protected]](mailto:[email protected])
+* Twitter: @hmlco
+
+## License
+
+Resolver is available under the MIT license. See the LICENSE file for more info.
+
 ## Additional Resouces
 
 * [API Documentation](https://hmlongco.github.io/Resolver/Documentation/API/Classes/Resolver.html)