comment documentations

Sources/Convenience Helpers/NSFetchedResultsController+Convenience.swift

@@ -33,6 +33,12 @@ public extension NSFetchedResultsController {
     
     /**
      Utility for creating an `NSFetchedResultsController` from a `DataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `ListMonitor`s abstraction.
+     
+     - parameter dataStack: the `DataStack` to observe objects from
+     - parameter fetchRequest: the `NSFetchRequest` instance to use with the `NSFetchedResultsController`
+     - parameter from: an optional `From` clause indicating the entity type. If not specified, the `fetchRequest` argument's `entity` property should already be set.
+     - parameter sectionBy: a `SectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections.
+     - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `Where`, `OrderBy`, and `Tweak` clauses.
      */
     @nonobjc
     public static func createForStack<T: NSManagedObject>(dataStack: DataStack, fetchRequest: NSFetchRequest, from: From<T>? = nil, sectionBy: SectionBy? = nil, fetchClauses: [FetchClause]) -> NSFetchedResultsController {

Sources/Convenience Helpers/NSProgress+Convenience.swift

@@ -35,6 +35,7 @@ public extension NSProgress {
     
     /**
      Sets a closure that the `NSProgress` calls whenever its `fractionCompleted` changes. You can use this instead of setting up KVO.
+     
      - parameter closure: the closure to execute on progress change
      */
     @nonobjc

Sources/CoreStoreError.swift

@@ -30,7 +30,7 @@ import CoreData
 // MARK: - CoreStoreError
 
 /**
- All errors thrown from CoreStore is expressed in `CoreStoreError` enum values.
+ All errors thrown from CoreStore are expressed in `CoreStoreError` enum values.
  */
 public enum CoreStoreError: ErrorType, CustomStringConvertible, CustomDebugStringConvertible, Hashable {
     
@@ -40,7 +40,7 @@ public enum CoreStoreError: ErrorType, CustomStringConvertible, CustomDebugStrin
     case Unknown
     
     /**
-     The `NSPersistentStore` could note be initialized because another store existed at the specified `NSURL`.
+     The `NSPersistentStore` could not be initialized because another store existed at the specified `NSURL`.
      */
     case DifferentStorageExistsAtURL(existingPersistentStoreURL: NSURL)
     
@@ -71,11 +71,20 @@ public enum CoreStoreError: ErrorType, CustomStringConvertible, CustomDebugStrin
     
         switch self {
             
-        case .Unknown:                      return CoreStoreErrorCode.UnknownError.rawValue
-        case .DifferentStorageExistsAtURL:  return CoreStoreErrorCode.DifferentPersistentStoreExistsAtURL.rawValue
-        case .MappingModelNotFound:         return CoreStoreErrorCode.MappingModelNotFound.rawValue
-        case .ProgressiveMigrationRequired: return CoreStoreErrorCode.ProgressiveMigrationRequired.rawValue
-        case .InternalError:                return CoreStoreErrorCode.InternalError.rawValue
+        case .Unknown:
+            return CoreStoreErrorCode.UnknownError.rawValue
+            
+        case .DifferentStorageExistsAtURL:
+            return CoreStoreErrorCode.DifferentPersistentStoreExistsAtURL.rawValue
+            
+        case .MappingModelNotFound:
+            return CoreStoreErrorCode.MappingModelNotFound.rawValue
+            
+        case .ProgressiveMigrationRequired:
+            return CoreStoreErrorCode.ProgressiveMigrationRequired.rawValue
+            
+        case .InternalError:
+            return CoreStoreErrorCode.InternalError.rawValue
         }
     }
     
@@ -162,7 +171,7 @@ public func == (lhs: CoreStoreError, rhs: CoreStoreError) -> Bool {
 // MARK: - CoreStoreErrorDomain
 
 /**
- The `NSError` error domain for `CoreStore`.
+ The `NSError` error domain string for `CSError`.
  */
 @nonobjc
 public let CoreStoreErrorDomain = "com.corestore.error"
@@ -221,6 +230,8 @@ public extension NSError {
     // MARK: Deprecated
 
     /**
+     Deprecated. Use `CoreStoreError` enum values instead.
+     
      If the error's domain is equal to `CoreStoreErrorDomain`, returns the associated `CoreStoreErrorCode`. For other domains, returns `nil`.
      */
     @available(*, deprecated=2.0.0, message="Use CoreStoreError enum values instead.")

Sources/Fetching and Querying/Concrete Clauses/From.swift

@@ -43,7 +43,6 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From<MyPersonEntity>())
      ```
@@ -55,10 +54,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified entity type.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From<MyPersonEntity>())
      ```
+     
      - parameter entity: the `NSManagedObject` type to be created
      */
     public init(_ entity: T.Type) {
@@ -68,10 +67,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified entity class.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From<MyPersonEntity>())
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      */
     public init(_ entityClass: AnyClass) {
@@ -81,10 +80,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From<MyPersonEntity>(nil, "Configuration1"))
      ```
+     
      - parameter configuration: the `NSPersistentStore` configuration name to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      - parameter otherConfigurations: an optional list of other configuration names to associate objects from (see `configuration` parameter)
      */
@@ -95,10 +94,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From<MyPersonEntity>(["Configuration1", "Configuration2"]))
      ```
+     
      - parameter configurations: a list of `NSPersistentStore` configuration names to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */
     public init(_ configurations: [String?]) {
@@ -108,10 +107,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From(MyPersonEntity.self, nil, "Configuration1"))
      ```
+     
      - parameter entity: the associated `NSManagedObject` type
      - parameter configuration: the `NSPersistentStore` configuration name to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      - parameter otherConfigurations: an optional list of other configuration names to associate objects from (see `configuration` parameter)
@@ -123,10 +122,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From(MyPersonEntity.self, ["Configuration1", "Configuration1"]))
      ```
+     
      - parameter entity: the associated `NSManagedObject` type
      - parameter configurations: a list of `NSPersistentStore` configuration names to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */
@@ -137,10 +136,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From(MyPersonEntity.self, nil, "Configuration1"))
      ```
+     
      - parameter entity: the associated `NSManagedObject` entity class
      - parameter configuration: the `NSPersistentStore` configuration name to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      - parameter otherConfigurations: an optional list of other configuration names to associate objects from (see `configuration` parameter)
@@ -152,10 +151,10 @@ public struct From<T: NSManagedObject> {
     
     /**
      Initializes a `From` clause with the specified configurations.
-     Sample Usage:
      ```
      let people = transaction.fetchAll(From(MyPersonEntity.self, ["Configuration1", "Configuration1"]))
      ```
+     
      - parameter entity: the associated `NSManagedObject` entity class
      - parameter configurations: a list of `NSPersistentStore` configuration names to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */

Sources/Fetching and Querying/Concrete Clauses/Select.swift

@@ -83,6 +83,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Where("employeeID", isEqualTo: 1111)
      )
      ```
+     
      - parameter keyPath: the attribute name
      - returns: a `SelectTerm` to a `Select` clause for querying an entity attribute
      */
@@ -99,6 +100,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Select<Int>(.Average("age"))
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "average(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the average value of an attribute
@@ -121,6 +123,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Select<Int>(.Count("employeeID"))
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "count(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for a count query
@@ -143,6 +146,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Select<Int>(.Maximum("age"))
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "max(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the maximum value for an attribute
@@ -165,6 +169,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Select<Int>(.Minimum("age"))
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "min(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the minimum value for an attribute
@@ -187,6 +192,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Select<Int>(.Sum("age"))
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "sum(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the sum value for an attribute
@@ -210,6 +216,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable {
          Where("employeeID", isEqualTo: 1111)
      )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "objecID" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the sum value for an attribute

Sources/Fetching and Querying/Concrete Clauses/Tweak.swift

@@ -46,8 +46,8 @@ public struct Tweak: FetchClause, QueryClause, DeleteClause {
     
     /**
      Initializes a `Tweak` clause with a closure where the `NSFetchRequest` may be configured.
-     - Important: `Tweak`'s closure is executed only just before the fetch occurs, so make sure that any values captured by the closure is not prone to race conditions. Also, some utilities (such as `ListMonitor`s) may keep `FetchClause`s in memory and may thus introduce retain cycles if reference captures are not handled properly.
      
+     - Important: `Tweak`'s closure is executed only just before the fetch occurs, so make sure that any values captured by the closure is not prone to race conditions. Also, some utilities (such as `ListMonitor`s) may keep `FetchClause`s in memory and may thus introduce retain cycles if reference captures are not handled properly.
      - parameter customization: a list of key path strings to group results with
      */
     public init(_ customization: (fetchRequest: NSFetchRequest) -> Void) {

Sources/Logging/CoreStoreLogger.swift

@@ -50,33 +50,33 @@ public protocol CoreStoreLogger {
     /**
      Handles log messages sent by the `CoreStore` framework.
      
-     :level: the severity of the log message
-     :message: the log message
-     :fileName: the source file name
-     :lineNumber: the source line number
-     :functionName: the source function name
+     - parameter level: the severity of the log message
+     - parameter message: the log message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
      */
     func log(level level: LogLevel, message: String, fileName: StaticString, lineNumber: Int, functionName: StaticString)
     
     /**
      Handles errors sent by the `CoreStore` framework.
      
-     :error: the error
-     :message: the error message
-     :fileName: the source file name
-     :lineNumber: the source line number
-     :functionName: the source function name
+     - parameter error: the error
+     - parameter message: the error message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
      */
     func log(error error: CoreStoreError, message: String, fileName: StaticString, lineNumber: Int, functionName: StaticString)
     
     /**
      Handles assertions made throughout the `CoreStore` framework.
      
-     :condition: the assertion condition
-     :message: the assertion message
-     :fileName: the source file name
-     :lineNumber: the source line number
-     :functionName: the source function name
+     - parameter condition: the assertion condition
+     - parameter message: the assertion message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
      */
     func assert(@autoclosure condition: () -> Bool, @autoclosure message: () -> String, fileName: StaticString, lineNumber: Int, functionName: StaticString)
     

Sources/Logging/DefaultLogger.swift

@@ -41,7 +41,16 @@ public final class DefaultLogger: CoreStoreLogger {
      Creates a `DefaultLogger`.
      */
     public init() { }
-   
+    
+    /**
+     Handles log messages sent by the `CoreStore` framework.
+     
+     - parameter level: the severity of the log message
+     - parameter message: the log message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
+     */
     public func log(level level: LogLevel, message: String, fileName: StaticString, lineNumber: Int, functionName: StaticString) {
         
         #if DEBUG
@@ -69,6 +78,15 @@ public final class DefaultLogger: CoreStoreLogger {
         #endif
     }
     
+    /**
+     Handles errors sent by the `CoreStore` framework.
+     
+     - parameter error: the error
+     - parameter message: the error message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
+     */
     public func log(error error: CoreStoreError, message: String, fileName: StaticString, lineNumber: Int, functionName: StaticString) {
         
         #if DEBUG
@@ -76,6 +94,15 @@ public final class DefaultLogger: CoreStoreLogger {
         #endif
     }
     
+    /**
+     Handles assertions made throughout the `CoreStore` framework.
+     
+     - parameter :condition: the assertion condition
+     - parameter message: the assertion message
+     - parameter fileName: the source file name
+     - parameter lineNumber: the source line number
+     - parameter functionName: the source function name
+     */
     public func assert(@autoclosure condition: () -> Bool, @autoclosure message: () -> String, fileName: StaticString, lineNumber: Int, functionName: StaticString) {
         
         #if DEBUG

Sources/Migrating/CoreStore+Migration.swift

@@ -47,8 +47,10 @@ public extension CoreStore {
          }
      )
      ```
+     
      - parameter storeType: the storage type
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public static func addStorage<T: StorageInterface where T: DefaultInitializableStore>(storeType: T.Type, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -69,8 +71,10 @@ public extension CoreStore {
          }
      )
      ```
+     
      - parameter storage: the storage
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public static func addStorage<T: StorageInterface>(storage: T, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -91,8 +95,10 @@ public extension CoreStore {
          }
      )
      ```
+     
      - parameter storeType: the local storage type
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public static func addStorage<T: LocalStorage where T: DefaultInitializableStore>(storeType: T.Type, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -113,8 +119,10 @@ public extension CoreStore {
          }
      )
      ```
+     
      - parameter storage: the local storage
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public static func addStorage<T: LocalStorage>(storage: T, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -127,6 +135,7 @@ public extension CoreStore {
 
      - parameter storage: the local storage
      - parameter completion: the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure's `MigrationResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public static func upgradeStorageIfNeeded<T: LocalStorage>(storage: T, completion: (MigrationResult) -> Void) throws -> NSProgress? {
@@ -138,6 +147,7 @@ public extension CoreStore {
      Checks the migration steps required for the storage to match the `defaultStack`'s managed object model version.
      
      - parameter storage: the local storage
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: a `MigrationType` array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, an error is thrown if either inspection of the store failed, or if no mapping model was found/inferred.
      */
     @warn_unused_result

Sources/Migrating/DataStack+Migration.swift

@@ -47,8 +47,10 @@ public extension DataStack {
          }
      )
      ```
+     
      - parameter storeType: the storage type
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public func addStorage<T: StorageInterface where T: DefaultInitializableStore>(storeType: T.Type, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -69,8 +71,10 @@ public extension DataStack {
          }
      )
      ```
+     
      - parameter storage: the storage
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public func addStorage<T: StorageInterface>(storage: T, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -130,8 +134,10 @@ public extension DataStack {
          }
      )
      ```
+     
      - parameter storeType: the local storage type
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public func addStorage<T: LocalStorage where T: DefaultInitializableStore>(storeType: T.Type, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -152,8 +158,10 @@ public extension DataStack {
          }
      )
      ```
+     
      - parameter storage: the local storage
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `SetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously. Note that the `LocalStorage` associated to the `SetupResult.Success` may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public func addStorage<T: LocalStorage>(storage: T, completion: (SetupResult<T>) -> Void) throws -> NSProgress? {
@@ -280,6 +288,7 @@ public extension DataStack {
      
      - parameter storage: the local storage
      - parameter completion: the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure's `MigrationResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a `.Failure` result if an error occurs asynchronously.
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: an `NSProgress` instance if a migration has started, or `nil` is no migrations are required
      */
     public func upgradeStorageIfNeeded<T: LocalStorage>(storage: T, completion: (MigrationResult) -> Void) throws -> NSProgress? {
@@ -321,6 +330,7 @@ public extension DataStack {
      Checks the migration steps required for the storage to match the `DataStack`'s managed object model version.
      
      - parameter storage: the local storage
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: a `MigrationType` array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, an error is thrown if either inspection of the store failed, or if no mapping model was found/inferred.
      */
     @warn_unused_result

Sources/Migrating/MigrationChain.swift

@@ -62,6 +62,9 @@ import CoreData
  */
 public struct MigrationChain: NilLiteralConvertible, StringLiteralConvertible, DictionaryLiteralConvertible, ArrayLiteralConvertible {
     
+    /**
+     Initializes the `MigrationChain` with empty values, which instructs the `DataStack` to use the .xcdatamodel's current version as the final version, and to disable progressive migrations.
+    */
     public init() {
         
         self.versionTree = [:]
@@ -70,6 +73,9 @@ public struct MigrationChain: NilLiteralConvertible, StringLiteralConvertible, D
         self.valid = true
     }
     
+    /**
+     Initializes the `MigrationChain` with a single model version, which instructs the `DataStack` to use the the specified version as the final version, and to disable progressive migrations.
+     */
     public init(_ value: String) {
         
         self.versionTree = [:]
@@ -78,6 +84,9 @@ public struct MigrationChain: NilLiteralConvertible, StringLiteralConvertible, D
         self.valid = true
     }
     
+    /**
+     Initializes the `MigrationChain` with a linear order of versions, which becomes the order of the `DataStack`'s progressive migrations.
+     */
     public init<T: CollectionType where T.Generator.Element == String, T.Index: BidirectionalIndexType>(_ elements: T) {
         
         CoreStore.assert(Set(elements).count == Array(elements).count, "\(typeName(MigrationChain))'s migration chain could not be created due to duplicate version strings.")
@@ -101,6 +110,9 @@ public struct MigrationChain: NilLiteralConvertible, StringLiteralConvertible, D
         self.valid = valid
     }
     
+    /**
+     Initializes the `MigrationChain` with a version tree, which becomes the order of the `DataStack`'s progressive migrations.
+     */
     public init(_ elements: [(String, String)]) {
         
         var valid = true
@@ -147,6 +159,9 @@ public struct MigrationChain: NilLiteralConvertible, StringLiteralConvertible, D
         self.valid = valid && Set(versionTree.keys).union(versionTree.values).filter { isVersionAmbiguous($0) }.count <= 0
     }
     
+    /**
+     Initializes the `MigrationChain` with a version tree, which becomes the order of the `DataStack`'s progressive migrations.
+     */
     public init(_ dictionary: [String: String]) {
         
         self.init(dictionary.map { $0 })

Sources/ObjectiveC/CSAsynchronousDataTransaction.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSAsynchronousDataTransaction` serves as the Objective-C bridging type for `AsynchronousDataTransaction`.
+ 
+ - SeeAlso: `AsynchronousDataTransaction`
  */
 @objc
 public final class CSAsynchronousDataTransaction: CSBaseDataTransaction {

Sources/ObjectiveC/CSBaseDataTransaction.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSBaseDataTransaction` serves as the Objective-C bridging type for `BaseDataTransaction`.
+ 
+ - SeeAlso: `BaseDataTransaction`
  */
 @objc
 public class CSBaseDataTransaction: NSObject, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSClauseTypes.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSFetchClause` implement clauses used to configure `NSFetchRequest`s.
+ 
+ - SeeAlso: `FetchClause`
  */
 @objc
 public protocol CSFetchClause {
@@ -44,6 +46,8 @@ public protocol CSFetchClause {
 
 /**
  The `CSQueryClause` implement clauses used to configure `NSFetchRequest`s.
+ 
+ - SeeAlso: `QueryClause`
  */
 @objc
 public protocol CSQueryClause {
@@ -57,6 +61,8 @@ public protocol CSQueryClause {
 
 /**
  The `CSDeleteClause` implement clauses used to configure `NSFetchRequest`s.
+ 
+ - SeeAlso: `DeleteClause`
  */
 @objc
 public protocol CSDeleteClause {

Sources/ObjectiveC/CSCoreStore+Migrating.swift

@@ -44,8 +44,10 @@ public extension CSCoreStore {
          }
          error: &error];
      ```
+     
      - parameter storage: the `CSInMemoryStore` instance
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     public static func addInMemoryStorage(storage: CSInMemoryStore, completion: (CSSetupResult) -> Void, error: NSErrorPointer) -> NSProgress? {
@@ -68,8 +70,10 @@ public extension CSCoreStore {
          }
          error: &error];
      ```
+     
      - parameter storage: the `CSSQLiteStore` instance
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously. Note that the `CSLocalStorage` associated to the `-[CSSetupResult storage]` may not always be the same instance as the parameter argument if a previous `CSLocalStorage` was already added at the same URL and with the same configuration.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     public static func addSQLiteStorage(storage: CSSQLiteStore, completion: (CSSetupResult) -> Void, error: NSErrorPointer) -> NSProgress? {
@@ -82,6 +86,7 @@ public extension CSCoreStore {
      
      - parameter storage: the `CSSQLiteStore` instance
      - parameter completion: the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure's `CSMigrationResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     @objc
@@ -94,6 +99,7 @@ public extension CSCoreStore {
      Checks the migration steps required for the `CSSQLiteStore` to match the `defaultStack`'s managed object model version.
      
      - parameter storage: the `CSSQLiteStore` instance
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: a `CSMigrationType` array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, `nil` is returned and the `error` argument is set if either inspection of the store failed, or if no mapping model was found/inferred.
      */
     @objc

Sources/ObjectiveC/CSCoreStore+Setup.swift

@@ -51,6 +51,7 @@ public extension CSCoreStore {
     
     /**
      Returns the entity class for the given entity name from the `defaultStack`'s model.
+     
      - parameter name: the entity name
      - returns: the `NSManagedObject` class for the given entity name, or `nil` if not found
      */
@@ -75,6 +76,7 @@ public extension CSCoreStore {
      CSSQLiteStore *storage = [CSCoreStore addInMemoryStorageAndWaitAndReturnError:&error];
      ```
      
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSInMemoryStore` added to the `defaultStack`
      */
     @objc
@@ -89,6 +91,7 @@ public extension CSCoreStore {
      CSSQLiteStore *storage = [CSCoreStore addSQLiteStorageAndWaitAndReturnError:&error];
      ```
      
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSSQLiteStore` added to the `defaultStack`
      */
     @objc
@@ -107,6 +110,7 @@ public extension CSCoreStore {
      ```
      
      - parameter storage: the `CSInMemoryStore`
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSInMemoryStore` added to the `defaultStack`
      */
     @objc
@@ -125,6 +129,7 @@ public extension CSCoreStore {
      ```
      
      - parameter storage: the `CSSQLiteStore`
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSSQLiteStore` added to the `defaultStack`
      */
     @objc

Sources/ObjectiveC/CSCoreStore.swift

@@ -30,14 +30,17 @@ import Foundation
 
 /**
  The `CSCoreStore` serves as the Objective-C bridging type for `CoreStore`.
+ 
+ - SeeAlso: `CoreStore`
  */
 @objc
 public final class CSCoreStore: NSObject {
     
     /**
-     The default `CSDataStack` instance to be used. If `defaultStack` is not set before the first time accessed, a default-configured `DataStack` will be created.
+     The default `CSDataStack` instance to be used. If `defaultStack` is not set before the first time accessed, a default-configured `CSDataStack` will be created.
      
-     Changing the `defaultStack` is thread safe, but it is recommended to setup stacks on a common queue (e.g. the main queue).
+     - SeeAlso: `CSDataStack`
+     - Note: Changing the `defaultStack` is thread safe, but it is recommended to setup `CSDataStacks` on a common queue (e.g. the main queue).
      */
     @objc
     public static var defaultStack: CSDataStack {

Sources/ObjectiveC/CSDataStack+Migrating.swift

@@ -44,8 +44,10 @@ public extension CSDataStack {
          }
          error: &error];
      ```
+     
      - parameter storage: the `CSInMemoryStore` instance
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     @objc
@@ -75,8 +77,10 @@ public extension CSDataStack {
          }
          error: &error];
      ```
+     
      - parameter storage: the `CSSQLiteStore` instance
      - parameter completion: the closure to be executed on the main queue when the process completes, either due to success or failure. The closure's `CSSetupResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously. Note that the `CSLocalStorage` associated to the `-[CSSetupResult storage]` may not always be the same instance as the parameter argument if a previous `CSLocalStorage` was already added at the same URL and with the same configuration.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     @objc
@@ -96,6 +100,7 @@ public extension CSDataStack {
      
      - parameter storage: the `CSSQLiteStore` instance
      - parameter completion: the closure to be executed on the main queue when the migration completes, either due to success or failure. The closure's `CSMigrationResult` argument indicates the result. This closure is NOT executed if an error is thrown, but will be executed with a failure `CSSetupResult` result if an error occurs asynchronously.
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: an `NSProgress` instance if a migration has started. `nil` if no migrations are required or if `error` was set.
      */
     @objc
@@ -114,6 +119,7 @@ public extension CSDataStack {
      Checks the migration steps required for the `CSSQLiteStore` to match the `CSDataStack`'s managed object model version.
      
      - parameter storage: the `CSSQLiteStore` instance
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: a `CSMigrationType` array indicating the migration steps required for the store, or an empty array if the file does not exist yet. Otherwise, `nil` is returned and the `error` argument is set if either inspection of the store failed, or if no mapping model was found/inferred.
      */
     @objc

Sources/ObjectiveC/CSDataStack.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSDataStack` serves as the Objective-C bridging type for `DataStack`.
+ 
+ - SeeAlso: `DataStack`
  */
 @objc
 public final class CSDataStack: NSObject, CoreStoreObjectiveCType {
@@ -160,6 +162,7 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType {
      CSSQLiteStore *storage = [dataStack addInMemoryStorageAndWaitAndReturnError:&error];
      ```
      
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSInMemoryStore` added to the stack
      */
     @objc
@@ -177,6 +180,7 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType {
      CSSQLiteStore *storage = [dataStack addSQLiteStorageAndWaitAndReturnError:&error];
      ```
      
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSSQLiteStore` added to the stack
      */
     @objc
@@ -198,6 +202,7 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType {
      ```
      
      - parameter storage: the `CSInMemoryStore`
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSInMemoryStore` added to the stack
      */
     @objc
@@ -219,6 +224,7 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType {
      ```
      
      - parameter storage: the `CSSQLiteStore`
+     - parameter error: the `NSError` pointer that indicates the reason in case of an failure
      - returns: the `CSSQLiteStore` added to the stack
      */
     @objc

Sources/ObjectiveC/CSError.swift

@@ -30,13 +30,17 @@ import CoreData
 // MARK: - CSError
 
 /**
- The `CSError` provides a facade for global CoreStore error declarations.
+ All errors thrown from CoreStore are expressed in `CSError`s.
+ 
+ - SeeAlso: `CoreStoreError`
  */
 @objc
 public final class CSError: NSError, CoreStoreObjectiveCType {
     
     /**
-     The `NSError` error domain for `CSCoreStore`.
+     The `NSError` error domain for `CSError`.
+     
+     - SeeAlso: `CoreStoreErrorErrorDomain`
      */
     @objc
     public static let errorDomain = CoreStoreErrorDomain
@@ -61,8 +65,6 @@ public final class CSError: NSError, CoreStoreObjectiveCType {
     
     // MARK: CoreStoreObjectiveCType
     
-    private var swiftError: CoreStoreError?
-    
     public var bridgeToSwift: CoreStoreError {
         
         if let swift = self.swiftError {
@@ -174,6 +176,11 @@ public final class CSError: NSError, CoreStoreObjectiveCType {
         
         super.init(coder: aDecoder)
     }
+    
+    
+    // MARK: Private
+    
+    private var swiftError: CoreStoreError?
 }
 
 
@@ -181,6 +188,9 @@ public final class CSError: NSError, CoreStoreObjectiveCType {
 
 /**
  The `NSError` error codes for `CSError.Domain`.
+ 
+ - SeeAlso: `CSError`
+ - SeeAlso: `CoreStoreError`
  */
 @objc
 public enum CSErrorCode: Int {

Sources/ObjectiveC/CSFrom.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSFrom` serves as the Objective-C bridging type for `From`.
+ 
+ - SeeAlso: `From`
  */
 @objc
 public final class CSFrom: NSObject, CoreStoreObjectiveCType {
@@ -40,6 +42,7 @@ public final class CSFrom: NSObject, CoreStoreObjectiveCType {
      ```
      MyPersonEntity *people = [transaction fetchAllFrom:[CSFrom entityClass:[MyPersonEntity class]]];
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      - returns: a `CSFrom` clause with the specified entity class
      */
@@ -54,6 +57,7 @@ public final class CSFrom: NSObject, CoreStoreObjectiveCType {
      ```
      MyPersonEntity *people = [transaction fetchAllFrom:[CSFrom entityClass:[MyPersonEntity class] configuration:@"Configuration1"]];
      ```
+     
      - parameter configuration: the `NSPersistentStore` configuration name to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      - parameter otherConfigurations: an optional list of other configuration names to associate objects from (see `configuration` parameter)
      - returns: a `CSFrom` clause with the specified configurations
@@ -69,6 +73,7 @@ public final class CSFrom: NSObject, CoreStoreObjectiveCType {
      ```
      MyPersonEntity *people = [transaction fetchAllFrom:[CSFrom entityClass:[MyPersonEntity class] configurations:@[[NSNull null], @"Configuration1"]]];
      ```
+     
      - parameter entity: the associated `NSManagedObject` entity class
      - parameter configurations: a list of `NSPersistentStore` configuration names to associate objects from. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `[NSNull null]` to use the default configuration.
      - returns: a `CSFrom` clause with the specified configurations

Sources/ObjectiveC/CSGroupBy.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSGroupBy` serves as the Objective-C bridging type for `GroupBy`.
+ 
+ - SeeAlso: `GroupBy`
  */
 @objc
 public final class CSGroupBy: NSObject, CSQueryClause, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSInMemoryStore.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSInMemoryStore` serves as the Objective-C bridging type for `InMemoryStore`.
+ 
+ - SeeAlso: `InMemoryStore`
  */
 @objc
 public final class CSInMemoryStore: NSObject, CSStorageInterface, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSInto.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSInto` serves as the Objective-C bridging type for `Into<T>`.
+ 
+ - SeeAlso: `Into`
  */
 @objc
 public final class CSInto: NSObject, CoreStoreObjectiveCType {
@@ -40,6 +42,7 @@ public final class CSInto: NSObject, CoreStoreObjectiveCType {
      ```
      MyPersonEntity *person = [transaction createInto:[CSInto entityClass:[MyPersonEntity class]]];
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      - returns: a `CSInto` clause with the specified entity class
      */
@@ -54,6 +57,7 @@ public final class CSInto: NSObject, CoreStoreObjectiveCType {
      ```
      MyPersonEntity *person = [transaction createInto:[CSInto entityClass:[MyPersonEntity class]]];
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      - parameter configuration: the `NSPersistentStore` configuration name to associate the object to. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      - returns: a `CSInto` clause with the specified configuration

Sources/ObjectiveC/CSListMonitor.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSListMonitor` serves as the Objective-C bridging type for `ListMonitor<T>`.
+ 
+ - SeeAlso: `ListMonitor`
  */
 @available(OSX, unavailable)
 @objc

Sources/ObjectiveC/CSListObserver.swift

@@ -37,6 +37,8 @@ import CoreData
      fetchClauses:@[[CSOrderBy sortDescriptor:[CSSortKey withKeyPath:@"lastName" ascending:YES]]]];
  [monitor addListObserver:self];
  ```
+ 
+ - SeeAlso: `ListObserver`
  */
 @available(OSX, unavailable)
 @objc
@@ -86,6 +88,8 @@ public protocol CSListObserver: class, AnyObject {
      fetchClauses:@[[CSOrderBy sortDescriptor:[CSSortKey withKeyPath:@"lastName" ascending:YES]]]];
  [monitor addListObjectObserver:self];
  ```
+ 
+ - SeeAlso: `ListObjectObserver`
  */
 @available(OSX, unavailable)
 @objc
@@ -145,6 +149,8 @@ public protocol CSListObjectObserver: CSListObserver {
      fetchClauses:@[[CSOrderBy sortDescriptor:[CSSortKey withKeyPath:@"lastName" ascending:YES]]]];
  [monitor addListSectionObserver:self];
  ```
+ 
+ - SeeAlso: `ListSectionObserver`
  */
 @available(OSX, unavailable)
 @objc

Sources/ObjectiveC/CSMigrationResult.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSMigrationResult` serves as the Objective-C bridging type for `MigrationResult`.
+ 
+ - SeeAlso: `MigrationResult`
  */
 @objc
 public final class CSMigrationResult: NSObject, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSMigrationType.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSMigrationType` serves as the Objective-C bridging type for `MigrationType`.
+ 
+ - SeeAlso: `MigrationType`
  */
 @objc
 public final class CSMigrationType: NSObject, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSObjectMonitor.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSObjectMonitor` serves as the Objective-C bridging type for `ObjectMonitor<T>`.
+ 
+ - SeeAlso: `ObjectMonitor`
  */
 @available(OSX, unavailable)
 @objc

Sources/ObjectiveC/CSObjectObserver.swift

@@ -35,6 +35,8 @@ import CoreData
  CSObjectMonitor *monitor = [CSCoreStore monitorObject:myObject];
  [monitor addObjectObserver:self];
  ```
+ 
+ - SeeAlso: `ObjectObserver`
  */
 @available(OSX, unavailable)
 @objc

Sources/ObjectiveC/CSOrderBy.swift

@@ -31,6 +31,9 @@ import CoreData
 
 /**
  The `CSSortKey` is a syntax-sugar class for `NSSortDescriptor` meant to be used with `CSOrderBy`.
+ 
+ - SeeAlso: `CSOrderBy`
+ - SeeAlso: `SortKey`
  */
 @objc
 public final class CSSortKey: NSSortDescriptor {
@@ -54,6 +57,8 @@ public final class CSSortKey: NSSortDescriptor {
 
 /**
  The `CSOrderBy` serves as the Objective-C bridging type for `OrderBy`.
+ 
+ - SeeAlso: `OrderBy`
  */
 @objc
 public final class CSOrderBy: NSObject, CSFetchClause, CSQueryClause, CSDeleteClause, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSSQliteStore.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSQLiteStore` serves as the Objective-C bridging type for `SQLiteStore`.
+ 
+ - SeeAlso: `SQLiteStore`
  */
 @objc
 public final class CSSQLiteStore: NSObject, CSLocalStorage, CoreStoreObjectiveCType {
@@ -58,8 +60,8 @@ public final class CSSQLiteStore: NSObject, CSLocalStorage, CoreStoreObjectiveCT
     
     /**
      Initializes an SQLite store interface from the given SQLite file name. When this instance is passed to the `CSDataStack`'s `-addStorage*:` methods, a new SQLite file will be created if it does not exist.
-     - Warning: The default SQLite file location for the `CSLegacySQLiteStore` and `CSSQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `CSLegacySQLiteStore` instead of `CSSQLiteStore`.
      
+     - Warning: The default SQLite file location for the `CSLegacySQLiteStore` and `CSSQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `CSLegacySQLiteStore` instead of `CSSQLiteStore`.
      - parameter fileName: the local filename for the SQLite persistent store in the "Application Support/<bundle id>" directory (or the "Caches/<bundle id>" directory on tvOS). Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter mappingModelBundles: a list of `NSBundle`s from which to search mapping models for migration
@@ -80,6 +82,7 @@ public final class CSSQLiteStore: NSObject, CSLocalStorage, CoreStoreObjectiveCT
     
     /**
      Initializes an `CSSQLiteStore` with an all-default settings: a `fileURL` pointing to a "<Application name>.sqlite" file in the "Application Support/<bundle id>" directory (or the "Caches/<bundle id>" directory on tvOS), a `nil` `configuration` pertaining to the "Default" configuration, a `mappingModelBundles` set to search all `NSBundle`s, and `localStorageOptions` set to `.AllowProgresiveMigration`.
+     
      - Warning: The default SQLite file location for the `CSLegacySQLiteStore` and `CSSQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `CSLegacySQLiteStore` instead of `CSSQLiteStore`.
      */
     @objc
@@ -151,9 +154,9 @@ public final class CSSQLiteStore: NSObject, CSLocalStorage, CoreStoreObjectiveCT
      Called by the `CSDataStack` to perform actual deletion of the store file from disk. Do not call directly! The `sourceModel` argument is a hint for the existing store's model version. For `CSSQLiteStore`, this converts the database's WAL journaling mode to DELETE before deleting the file.
      */
     @objc
-    public func eraseStorageAndWait(soureModel soureModel: NSManagedObjectModel) throws {
+    public func eraseStorageAndWait(soureModel soureModel: NSManagedObjectModel, error: NSErrorPointer) -> Bool {
         
-        try bridge {
+        return bridge(error) {
             
             try self.bridgeToSwift.eraseStorageAndWait(soureModel: soureModel)
         }

Sources/ObjectiveC/CSSaveResult.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSaveResult` serves as the Objective-C bridging type for `SaveResult`.
+ 
+ - SeeAlso: `SaveResult`
  */
 @objc
 public final class CSSaveResult: NSObject, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSSectionBy.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSectionBy` serves as the Objective-C bridging type for `SectionBy`.
+ 
+ - SeeAlso: `SectionBy`
  */
 @available(OSX, unavailable)
 @objc

Sources/ObjectiveC/CSSelect.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSelectTerm` serves as the Objective-C bridging type for `SelectTerm`.
+ 
+ - SeeAlso: `SelectTerm`
  */
 @objc
 public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
@@ -43,6 +45,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          select:[CSSelect stringForTerm:[CSSelectTerm attribute:@"fullName"]]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
      ```
+     
      - parameter keyPath: the attribute name
      - returns: a `CSSelectTerm` to a `CSSelect` clause for querying an entity attribute
      */
@@ -58,6 +61,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm average:@"age" as:nil]]];
      ```
+     
      - parameter keyPath: the attribute name
      - parameter `as`: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "average(<attributeName>)" is used
      - returns: a `CSSelectTerm` to a `CSSelect` clause for querying the average value of an attribute
@@ -74,6 +78,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm count:@"employeeID" as:nil]]];
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "count(<attributeName>)" is used
      - returns: a `SelectTerm` to a `Select` clause for a count query
@@ -90,6 +95,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm maximum:@"age" as:nil]]];
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "max(<attributeName>)" is used
      - returns: a `CSSelectTerm` to a `CSSelect` clause for querying the maximum value for an attribute
@@ -106,6 +112,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm minimum:@"age" as:nil]]];
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "min(<attributeName>)" is used
      - returns: a `CSSelectTerm` to a `CSSelect` clause for querying the minimum value for an attribute
@@ -122,6 +129,7 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm sum:@"age" as:nil]]];
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "sum(<attributeName>)" is used
      - returns: a `CSSelectTerm` to a `CSSelect` clause for querying the sum value for an attribute
@@ -138,13 +146,8 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect objectIDForTerm:[CSSelectTerm objectIDAs:nil]]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
-     
-     let objectID = CoreStore.queryValue(
-     From(MyPersonEntity),
-     Select<NSManagedObjectID>(.ObjectID()),
-     Where("employeeID", isEqualTo: 1111)
-     )
      ```
+     
      - parameter keyPath: the attribute name
      - parameter alias: the dictionary key to use to access the result. Ignored when the query return value is not an `NSDictionary`. If `nil`, the default key "objecID" is used
      - returns: a `SelectTerm` to a `Select` clause for querying the sum value for an attribute
@@ -202,6 +205,8 @@ extension SelectTerm: CoreStoreSwiftType {
 
 /**
  The `CSSelect` serves as the Objective-C bridging type for `Select`.
+ 
+ - SeeAlso: `Select`
  */
 @objc
 public final class CSSelect: NSObject {
@@ -213,6 +218,7 @@ public final class CSSelect: NSObject {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect numberForTerm:[CSSelectTerm maximum:@"age" as:nil]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -228,6 +234,7 @@ public final class CSSelect: NSObject {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect decimalNumberForTerm:[CSSelectTerm average:@"age" as:nil]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -244,6 +251,7 @@ public final class CSSelect: NSObject {
          select:[CSSelect stringForTerm:[CSSelectTerm attribute:@"fullName"]]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -259,6 +267,7 @@ public final class CSSelect: NSObject {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect dateForTerm:[CSSelectTerm maximum:@"updatedDate" as:nil]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -275,6 +284,7 @@ public final class CSSelect: NSObject {
          select:[CSSelect dataForTerm:[CSSelectTerm attribute:@"imageData" as:nil]]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -291,6 +301,7 @@ public final class CSSelect: NSObject {
          select:[CSSelect objectID]
          fetchClauses:@[[CSWhere keyPath:@"employeeID" isEqualTo: @1111]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -306,6 +317,7 @@ public final class CSSelect: NSObject {
          queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
          select:[CSSelect dictionaryForTerm:[CSSelectTerm maximum:@"age" as:nil]]];
      ```
+     
      - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query
      - returns: a `CSSelect` clause for querying an entity attribute
      */
@@ -314,6 +326,20 @@ public final class CSSelect: NSObject {
         return self.init(Select<NSDictionary>(term.bridgeToSwift))
     }
     
+    /**
+     Creates a `CSSelect` clause for querying `NSDictionary` of an entity's attribute keys and values.
+     ```
+     NSDictionary *keyValues = [CSCoreStore
+         queryValueFrom:[CSFrom entityClass:[MyPersonEntity class]]
+         select:[CSSelect dictionaryForTerms:@[
+             [CSSelectTerm attribute:@"name" as:nil],
+             [CSSelectTerm attribute:@"age" as:nil]
+         ]]];
+     ```
+     
+     - parameter terms: the `CSSelectTerm`s specifying the attribute/aggregate values to query
+     - returns: a `CSSelect` clause for querying an entity attribute
+     */
     public static func dictionaryForTerms(terms: [CSSelectTerm]) -> CSSelect {
         
         return self.init(Select<NSDictionary>(terms.map { $0.bridgeToSwift }))

Sources/ObjectiveC/CSSetupResult.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSetupResult` serves as the Objective-C bridging type for `SetupResult`.
+ 
+ - SeeAlso: `SetupResult`
  */
 @objc
 public final class CSSetupResult: NSObject {

Sources/ObjectiveC/CSStorageInterface.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSStorageInterface` serves as the Objective-C bridging type for `StorageInterface`.
+ 
+ - SeeAlso: `StorageInterface`
  */
 @objc
 public protocol CSStorageInterface {
@@ -59,6 +61,8 @@ public protocol CSStorageInterface {
 
 /**
  The `CSLocalStorageOptions` provides settings that tells the `CSDataStack` how to setup the persistent store for `CSLocalStorage` implementers.
+ 
+ - SeeAlso: `LocalStorageOptions`
  */
 @objc
 public enum CSLocalStorageOptions: Int {
@@ -89,6 +93,8 @@ public enum CSLocalStorageOptions: Int {
 
 /**
  The `CSLocalStorage` serves as the Objective-C bridging type for `LocalStorage`.
+ 
+ - SeeAlso: `LocalStorage`
  */
 @objc
 public protocol CSLocalStorage: CSStorageInterface {
@@ -115,5 +121,5 @@ public protocol CSLocalStorage: CSStorageInterface {
      Called by the `CSDataStack` to perform actual deletion of the store file from disk. Do not call directly! The `sourceModel` argument is a hint for the existing store's model version. Implementers can use the `sourceModel` to perform necessary store operations. (SQLite stores for example, can convert WAL journaling mode to DELETE before deleting)
      */
     @objc
-    func eraseStorageAndWait(soureModel soureModel: NSManagedObjectModel) throws
+    func eraseStorageAndWait(soureModel soureModel: NSManagedObjectModel, error: NSErrorPointer) -> Bool
 }

Sources/ObjectiveC/CSSynchronousDataTransaction.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSSynchronousDataTransaction` serves as the Objective-C bridging type for `SynchronousDataTransaction`.
+ 
+ - SeeAlso: `SynchronousDataTransaction`
  */
 @objc
 public final class CSSynchronousDataTransaction: CSBaseDataTransaction {

Sources/ObjectiveC/CSTweak.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSTweak` serves as the Objective-C bridging type for `Tweak`.
+ 
+ - SeeAlso: `Tweak`
  */
 @objc
 public final class CSTweak: NSObject, CSFetchClause, CSQueryClause, CSDeleteClause, CoreStoreObjectiveCType {

Sources/ObjectiveC/CSUnsafeDataTransaction.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSUnsafeDataTransaction` serves as the Objective-C bridging type for `UnsafeDataTransaction`.
+ 
+ - SeeAlso: `UnsafeDataTransaction`
  */
 @objc
 public final class CSUnsafeDataTransaction: CSBaseDataTransaction {

Sources/ObjectiveC/CSWhere.swift

@@ -31,6 +31,8 @@ import CoreData
 
 /**
  The `CSWhere` serves as the Objective-C bridging type for `Where`.
+ 
+ - SeeAlso: `Where`
  */
 @objc
 public final class CSWhere: NSObject, CSFetchClause, CSQueryClause, CSDeleteClause, CoreStoreObjectiveCType {

Sources/ObjectiveC/CoreStoreBridge.swift

@@ -28,22 +28,43 @@ import Foundation
 
 // MARK: - CoreStoreObjectiveCType
 
+/**
+ `CoreStoreObjectiveCType`s are Objective-C accessible classes that represent CoreStore's Swift types.
+ */
 public protocol CoreStoreObjectiveCType: class, AnyObject {
     
+    /**
+     The corresponding Swift type
+     */
     associatedtype SwiftType
     
+    /**
+     The bridged Swift instance
+     */
     var bridgeToSwift: SwiftType { get }
     
+    /**
+     Initializes this instance with the Swift instance to bridge from
+     */
     init(_ swiftValue: SwiftType)
 }
 
 
 // MARK: - CoreStoreSwiftType
 
+/**
+ `CoreStoreSwiftType`s are CoreStore's Swift types that are bridgeable to Objective-C.
+ */
 public protocol CoreStoreSwiftType {
     
+    /**
+     The corresponding Objective-C type
+     */
     associatedtype ObjectiveCType
     
+    /**
+     The bridged Objective-C instance
+     */
     var bridgeToObjectiveC: ObjectiveCType { get }
 }
 
@@ -107,6 +128,21 @@ internal func bridge<T: CoreStoreSwiftType>(error: NSErrorPointer, @noescape _ c
     }
 }
 
+internal func bridge(error: NSErrorPointer, @noescape _ closure: () throws -> Void) -> Bool {
+    
+    do {
+        
+        try closure()
+        error.memory = nil
+        return true
+    }
+    catch let swiftError {
+        
+        error.memory = swiftError.bridgeToObjectiveC
+        return false
+    }
+}
+
 internal func bridge<T>(error: NSErrorPointer, @noescape _ closure: () throws -> T?) -> T? {
     
     do {

Sources/ObjectiveC/NSFetchedResultsController+ObjectiveC.swift

@@ -33,7 +33,13 @@ import CoreData
 public extension NSFetchedResultsController {
     
     /**
-     Utility for creating an `NSFetchedResultsController` from a `CSDataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `CSListMonitor`s abstraction.
+     Utility for creating an `NSFetchedResultsController` from a `CSDataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `CSListMonitor`s abstractio
+     
+     - parameter dataStack: the `CSDataStack` to observe objects from
+     - parameter fetchRequest: the `NSFetchRequest` instance to use with the `NSFetchedResultsController`
+     - parameter from: an optional `CSFrom` clause indicating the entity type. If not specified, the `fetchRequest` argument's `entity` property should already be set.
+     - parameter sectionBy: a `CSSectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections.
+     - parameter fetchClauses: a series of `FetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses.
      */
     @objc
     public static func cs_createForStack(dataStack: CSDataStack, fetchRequest: NSFetchRequest, from: CSFrom?, sectionBy: CSSectionBy?, fetchClauses: [CSFetchClause]) -> NSFetchedResultsController {

Sources/ObjectiveC/NSProgress+ObjectiveC.swift

@@ -32,6 +32,7 @@ public extension NSProgress {
     
     /**
      Sets a closure that the `NSProgress` calls whenever its `fractionCompleted` changes. You can use this instead of setting up KVO.
+     
      - parameter closure: the closure to execute on progress change
      */
     @objc

Sources/Observing/SectionBy.swift

@@ -54,8 +54,8 @@ public struct SectionBy {
     
     /**
      Initializes a `SectionBy` clause with the key path to use to group `ListMonitor` objects into sections, and a closure to transform the value for the key path to an appropriate section name
-     - Important: Some utilities (such as `ListMonitor`s) may keep `SectionBy`s in memory and may thus introduce retain cycles if reference captures are not handled properly.
      
+     - Important: Some utilities (such as `ListMonitor`s) may keep `SectionBy`s in memory and may thus introduce retain cycles if reference captures are not handled properly.
      - parameter sectionKeyPath: the key path to use to group the objects into sections
      - parameter sectionIndexTransformer: a closure to transform the value for the key path to an appropriate section name
      */

Sources/Saving and Processing/Into.swift

@@ -43,7 +43,6 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause.
-     Sample Usage:
      ```
      let person = transaction.create(Into<MyPersonEntity>())
      ```
@@ -55,10 +54,10 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause with the specified entity type.
-     Sample Usage:
      ```
      let person = transaction.create(Into(MyPersonEntity))
      ```
+     
      - parameter entity: the `NSManagedObject` type to be created
      */
     public init(_ entity: T.Type) {
@@ -68,10 +67,10 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause with the specified entity class.
-     Sample Usage:
      ```
      let person = transaction.create(Into(MyPersonEntity))
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      */
     public init(_ entityClass: AnyClass) {
@@ -81,10 +80,10 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause with the specified configuration.
-     Sample Usage:
      ```
      let person = transaction.create(Into<MyPersonEntity>("Configuration1"))
      ```
+     
      - parameter configuration: the `NSPersistentStore` configuration name to associate the object to. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */
     public init(_ configuration: String?) {
@@ -94,10 +93,10 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause with the specified entity type and configuration.
-     Sample Usage:
      ```
      let person = transaction.create(Into(MyPersonEntity.self, "Configuration1"))
      ```
+     
      - parameter entity: the `NSManagedObject` type to be created
      - parameter configuration: the `NSPersistentStore` configuration name to associate the object to. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */
@@ -108,10 +107,10 @@ public struct Into<T: NSManagedObject>: Hashable {
     
     /**
      Initializes an `Into` clause with the specified entity class and configuration.
-     Sample Usage:
      ```
      let person = transaction.create(Into(MyPersonEntity.self, "Configuration1"))
      ```
+     
      - parameter entityClass: the `NSManagedObject` class type to be created
      - parameter configuration: the `NSPersistentStore` configuration name to associate the object to. This parameter is required if multiple configurations contain the created `NSManagedObject`'s entity type. Set to `nil` to use the default configuration.
      */

Sources/Saving and Processing/NSManagedObject+Transaction.swift

@@ -36,7 +36,7 @@ public extension NSManagedObject {
      
      When using an `UnsafeDataTransaction` and passing around a temporary object, you can use this property to execute fetches and updates to the transaction without having to pass around both the object and the transaction instances.
      
-     Note that the internal reference to the transaction is `weak`, and it is still the developer's responsibility to retain a strong reference to the `UnsafeDataTransaction`.
+     - Note: The internal reference to the transaction is `weak`, and it is still the developer's responsibility to retain a strong reference to the `UnsafeDataTransaction`.
      */
     @nonobjc
     public var unsafeDataTransaction: UnsafeDataTransaction? {

Sources/Saving and Processing/UnsafeDataTransaction.swift

@@ -118,7 +118,7 @@ public final class UnsafeDataTransaction: BaseDataTransaction {
     /**
      Returns the `NSManagedObjectContext` for this unsafe transaction. Use only for cases where external frameworks need an `NSManagedObjectContext` instance to work with.
      
-     Note that it is the developer's responsibility to ensure the following:
+     - Note: It is the developer's responsibility to ensure the following:
      - that the `UnsafeDataTransaction` that owns this context should be strongly referenced and prevented from being deallocated during the context's lifetime
      - that all saves will be done either through the `UnsafeDataTransaction`'s `commit(...)` method, or by calling `save()` manually on the context, its parent, and all other ancestor contexts if there are any.
      */

Sources/Setup/CoreStore+Setup.swift

@@ -78,6 +78,7 @@ public extension CoreStore {
      ```
      
      - parameter storeType: the `StorageInterface` type
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the `StorageInterface` added to the `defaultStack`
      */
     public static func addStorageAndWait<T: StorageInterface where T: DefaultInitializableStore>(storeType: T.Type) throws -> T {
@@ -92,6 +93,7 @@ public extension CoreStore {
      ```
      
      - parameter storage: the `StorageInterface`
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the `StorageInterface` added to the `defaultStack`
      */
     public static func addStorageAndWait<T: StorageInterface>(storage: T) throws -> T {
@@ -106,6 +108,7 @@ public extension CoreStore {
      ```
      
      - parameter storeType: the `LocalStorageface` type
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the local storage added to the `defaultStack`
      */
     public static func addStorageAndWait<T: LocalStorage where T: DefaultInitializableStore>(storageType: T.Type) throws -> T {
@@ -120,6 +123,7 @@ public extension CoreStore {
      ```
      
      - parameter storage: the local storage
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the local storage added to the `defaultStack`. Note that this may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
      */
     public static func addStorageAndWait<T: LocalStorage>(storage: T) throws -> T {

Sources/Setup/DataStack.swift

@@ -117,6 +117,7 @@ public final class DataStack {
      try dataStack.addStorageAndWait()
      ```
      
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the local SQLite storage added to the stack
      */
     public func addStorageAndWait() throws -> SQLiteStore {
@@ -131,6 +132,7 @@ public final class DataStack {
      ```
      
      - parameter storeType: the `StorageInterface` type
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the `StorageInterface` added to the stack
      */
     public func addStorageAndWait<T: StorageInterface where T: DefaultInitializableStore>(storeType: T.Type) throws -> T {
@@ -145,6 +147,7 @@ public final class DataStack {
      ```
      
      - parameter storage: the `StorageInterface`
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the `StorageInterface` added to the stack
      */
     public func addStorageAndWait<T: StorageInterface>(storage: T) throws -> T {
@@ -184,6 +187,7 @@ public final class DataStack {
      ```
      
      - parameter storeType: the `LocalStorageface` type
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the local storage added to the stack
      */
     public func addStorageAndWait<T: LocalStorage where T: DefaultInitializableStore>(storageType: T.Type) throws -> T {
@@ -198,6 +202,7 @@ public final class DataStack {
      ```
      
      - parameter storage: the local storage
+     - throws: a `CoreStoreError` value indicating the failure
      - returns: the local storage added to the stack. Note that this may not always be the same instance as the parameter argument if a previous `LocalStorage` was already added at the same URL and with the same configuration.
      */
     public func addStorageAndWait<T: LocalStorage>(storage: T) throws -> T {

Sources/Setup/StorageInterfaces/InMemoryStore.swift

@@ -35,7 +35,6 @@ public final class InMemoryStore: StorageInterface, DefaultInitializableStore {
     
     /**
      Initializes an `InMemoryStore` for the specified configuration
-     
      - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration.
      */
     public init(configuration: String?) {

Sources/Setup/StorageInterfaces/LegacySQLiteStore.swift

@@ -30,6 +30,7 @@ import Foundation
 
 /**
  A storage interface backed by an SQLite database that was created before CoreStore 2.0.0.
+ 
  - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
  */
 public final class LegacySQLiteStore: LocalStorage, DefaultInitializableStore {
@@ -52,8 +53,8 @@ public final class LegacySQLiteStore: LocalStorage, DefaultInitializableStore {
     
     /**
      Initializes an SQLite store interface from the given SQLite file name. When this instance is passed to the `DataStack`'s `addStorage()` methods, a new SQLite file will be created if it does not exist.
-     - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      
+     - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      - parameter fileName: the local filename for the SQLite persistent store in the "Application Support" directory (or the "Caches" directory on tvOS). Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter mappingModelBundles: a list of `NSBundle`s from which to search mapping models for migration.
@@ -75,6 +76,7 @@ public final class LegacySQLiteStore: LocalStorage, DefaultInitializableStore {
     
     /**
      Initializes an `LegacySQLiteStore` with an all-default settings: a `fileURL` pointing to a "<Application name>.sqlite" file in the "Application Support" directory (or the "Caches" directory on tvOS), a `nil` `configuration` pertaining to the "Default" configuration, a `mappingModelBundles` set to search all `NSBundle`s, and `localStorageOptions` set to `.AllowProgresiveMigration`.
+     
      - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      */
     public init() {

Sources/Setup/StorageInterfaces/SQLiteStore.swift

@@ -30,6 +30,7 @@ import CoreData
 
 /**
  A storage interface that is backed by an SQLite database.
+ 
  - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
  */
 public final class SQLiteStore: LocalStorage, DefaultInitializableStore {
@@ -52,8 +53,8 @@ public final class SQLiteStore: LocalStorage, DefaultInitializableStore {
     
     /**
      Initializes an SQLite store interface from the given SQLite file name. When this instance is passed to the `DataStack`'s `addStorage()` methods, a new SQLite file will be created if it does not exist.
-     - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      
+     - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      - parameter fileName: the local filename for the SQLite persistent store in the "Application Support/<bundle id>" directory (or the "Caches/<bundle id>" directory on tvOS). Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter configuration: an optional configuration name from the model file. If not specified, defaults to `nil`, the "Default" configuration. Note that if you have multiple configurations, you will need to specify a different `fileName` explicitly for each of them.
      - parameter mappingModelBundles: a list of `NSBundle`s from which to search mapping models for migration
@@ -73,6 +74,7 @@ public final class SQLiteStore: LocalStorage, DefaultInitializableStore {
     
     /**
      Initializes an `SQLiteStore` with an all-default settings: a `fileURL` pointing to a "<Application name>.sqlite" file in the "Application Support/<bundle id>" directory (or the "Caches/<bundle id>" directory on tvOS), a `nil` `configuration` pertaining to the "Default" configuration, a `mappingModelBundles` set to search all `NSBundle`s, and `localStorageOptions` set to `.AllowProgresiveMigration`.
+     
      - Warning: The default SQLite file location for the `LegacySQLiteStore` and `SQLiteStore` are different. If the app was depending on CoreStore's default directories prior to 2.0.0, make sure to use `LegacySQLiteStore` instead of `SQLiteStore`.
      */
     public init() {

Sources/Setup/StorageInterfaces/StorageInterface.swift

@@ -137,7 +137,7 @@ public protocol LocalStorage: StorageInterface {
     var localStorageOptions: LocalStorageOptions { get }
     
     /**
-     Called by the `DataStack` to perform actual deletion of the store file from disk. Do not call directly! The `sourceModel` argument is a hint for the existing store's model version. Implementers can use the `sourceModel` to perform necessary store operations. (SQLite stores for example, can convert WAL journaling mode to DELETE before deleting)
+     Called by the `DataStack` to perform actual deletion of the store file from disk. **Do not call directly!** The `sourceModel` argument is a hint for the existing store's model version. Implementers can use the `sourceModel` to perform necessary store operations. (SQLite stores for example, can convert WAL journaling mode to DELETE before deleting)
      */
     func eraseStorageAndWait(soureModel soureModel: NSManagedObjectModel) throws
 }