 import ReactiveCocoa
 
 class UsersViewModel {
+    
+    /// The cononical list of UserViewModels vended to UsersViewController.
+    /// Should only be updated on viewModelsQueue.
     var userViewModels: [UserViewModel]? = nil
     
+    /// Data source of User objects.
     private let userController: UserController
+    
+    /// Data source of image data.
     private let imageController: ImageController
     
+    /// RAC Action that vends [UserViewModel].
+    /// At the moment we assume this will never error, although real requests would handle that case.
     private let fetchUserViewModelsAction: Action<Void, [UserViewModel], NoError>
 
+    /// Signal/Observer pair whose events represent a full reload of userViewModels.
     let reloadSignal: Signal<Void, NoError>
     private let reloadObserver: Observer<Void, NoError>
     
+    /// Signal/Observer pair whose events represent a change to some indexPaths.
     let reloadIndexPathsSignal: Signal<[NSIndexPath], NoError>
     private let reloadIndexPathsObserver: Observer<[NSIndexPath], NoError>
     
+    /// All updates to userViewModels should be performed on this queue.
+    /// TODO: should this be QueueScheduler.mainQueueScheduler because that's where userViewModels is observed?
     let viewModelsQueue = QueueScheduler(qos: QOS_CLASS_USER_INITIATED, name: "com.twocentstudios.UserList.viewmodels")
+    
+    /// A general queue for performing view model fetching and transformations.
     let workQueue = QueueScheduler(qos: QOS_CLASS_DEFAULT, name: "com.twocentstudios.UserList.work")
+    
+    /// All image requests run on this queue.
+    /// TODO: Figure out how to make this a concurrent queue.
     let imageQueue = QueueScheduler(qos: QOS_CLASS_DEFAULT, name: "com.twocentstudios.UserList.image")
     
     init(userController: UserController, imageController: ImageController) {

        (reloadIndexPathsSignal, reloadIndexPathsObserver) = Signal<[NSIndexPath], NoError>.pipe()
        
        fetchUserViewModelsAction = Action { [unowned workQueue] _ in
            return SignalProducer(value: 100)
                .observeOn(workQueue)
                .flatMap(.Latest, transform: userController.fetchRandomUsersProducer)

                }
        }
        
        /// When new values are vended by fetchUserViewModelsAction, update userViewModels on viewModelsQueue.
        fetchUserViewModelsAction.values
            .observeOn(viewModelsQueue)
            .observeNext { [unowned self] userViewModels in
