From dccc958ef13353dfaecb053da1904e0841b44393 Mon Sep 17 00:00:00 2001 From: John Rommel Estropia Date: Sun, 3 Apr 2016 19:47:25 +0900 Subject: [PATCH] comment documentations --- ...FetchedResultsController+Convenience.swift | 6 +++ .../NSProgress+Convenience.swift | 1 + Sources/CoreStoreError.swift | 27 +++++++++---- .../Concrete Clauses/From.swift | 17 ++++----- .../Concrete Clauses/Select.swift | 7 ++++ .../Concrete Clauses/Tweak.swift | 2 +- Sources/Logging/CoreStoreLogger.swift | 30 +++++++-------- Sources/Logging/DefaultLogger.swift | 29 +++++++++++++- Sources/Migrating/CoreStore+Migration.swift | 10 +++++ Sources/Migrating/DataStack+Migration.swift | 10 +++++ Sources/Migrating/MigrationChain.swift | 15 ++++++++ .../CSAsynchronousDataTransaction.swift | 2 + .../ObjectiveC/CSBaseDataTransaction.swift | 2 + Sources/ObjectiveC/CSClauseTypes.swift | 6 +++ .../ObjectiveC/CSCoreStore+Migrating.swift | 6 +++ Sources/ObjectiveC/CSCoreStore+Setup.swift | 5 +++ Sources/ObjectiveC/CSCoreStore.swift | 7 +++- .../ObjectiveC/CSDataStack+Migrating.swift | 6 +++ Sources/ObjectiveC/CSDataStack.swift | 6 +++ Sources/ObjectiveC/CSError.swift | 18 +++++++-- Sources/ObjectiveC/CSFrom.swift | 5 +++ Sources/ObjectiveC/CSGroupBy.swift | 2 + Sources/ObjectiveC/CSInMemoryStore.swift | 2 + Sources/ObjectiveC/CSInto.swift | 4 ++ Sources/ObjectiveC/CSListMonitor.swift | 2 + Sources/ObjectiveC/CSListObserver.swift | 6 +++ Sources/ObjectiveC/CSMigrationResult.swift | 2 + Sources/ObjectiveC/CSMigrationType.swift | 2 + Sources/ObjectiveC/CSObjectMonitor.swift | 2 + Sources/ObjectiveC/CSObjectObserver.swift | 2 + Sources/ObjectiveC/CSOrderBy.swift | 5 +++ Sources/ObjectiveC/CSSQliteStore.swift | 9 +++-- Sources/ObjectiveC/CSSaveResult.swift | 2 + Sources/ObjectiveC/CSSectionBy.swift | 2 + Sources/ObjectiveC/CSSelect.swift | 38 ++++++++++++++++--- Sources/ObjectiveC/CSSetupResult.swift | 2 + Sources/ObjectiveC/CSStorageInterface.swift | 8 +++- .../CSSynchronousDataTransaction.swift | 2 + Sources/ObjectiveC/CSTweak.swift | 2 + .../ObjectiveC/CSUnsafeDataTransaction.swift | 2 + Sources/ObjectiveC/CSWhere.swift | 2 + Sources/ObjectiveC/CoreStoreBridge.swift | 36 ++++++++++++++++++ ...SFetchedResultsController+ObjectiveC.swift | 8 +++- .../ObjectiveC/NSProgress+ObjectiveC.swift | 1 + Sources/Observing/SectionBy.swift | 2 +- Sources/Saving and Processing/Into.swift | 11 +++--- .../NSManagedObject+Transaction.swift | 2 +- .../UnsafeDataTransaction.swift | 2 +- Sources/Setup/CoreStore+Setup.swift | 4 ++ Sources/Setup/DataStack.swift | 5 +++ .../StorageInterfaces/InMemoryStore.swift | 1 - .../StorageInterfaces/LegacySQLiteStore.swift | 4 +- .../Setup/StorageInterfaces/SQLiteStore.swift | 4 +- .../StorageInterfaces/StorageInterface.swift | 2 +- 54 files changed, 333 insertions(+), 64 deletions(-) diff --git a/Sources/Convenience Helpers/NSFetchedResultsController+Convenience.swift b/Sources/Convenience Helpers/NSFetchedResultsController+Convenience.swift index cbadc3a..e9f3310 100644 --- a/Sources/Convenience Helpers/NSFetchedResultsController+Convenience.swift +++ b/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(dataStack: DataStack, fetchRequest: NSFetchRequest, from: From? = nil, sectionBy: SectionBy? = nil, fetchClauses: [FetchClause]) -> NSFetchedResultsController { diff --git a/Sources/Convenience Helpers/NSProgress+Convenience.swift b/Sources/Convenience Helpers/NSProgress+Convenience.swift index deca366..cd06165 100644 --- a/Sources/Convenience Helpers/NSProgress+Convenience.swift +++ b/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 diff --git a/Sources/CoreStoreError.swift b/Sources/CoreStoreError.swift index 3e66664..57048ab 100644 --- a/Sources/CoreStoreError.swift +++ b/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.") diff --git a/Sources/Fetching and Querying/Concrete Clauses/From.swift b/Sources/Fetching and Querying/Concrete Clauses/From.swift index a2f8f9f..f4111ca 100644 --- a/Sources/Fetching and Querying/Concrete Clauses/From.swift +++ b/Sources/Fetching and Querying/Concrete Clauses/From.swift @@ -43,7 +43,6 @@ public struct From { /** Initializes a `From` clause. - Sample Usage: ``` let people = transaction.fetchAll(From()) ``` @@ -55,10 +54,10 @@ public struct From { /** Initializes a `From` clause with the specified entity type. - Sample Usage: ``` let people = transaction.fetchAll(From()) ``` + - parameter entity: the `NSManagedObject` type to be created */ public init(_ entity: T.Type) { @@ -68,10 +67,10 @@ public struct From { /** Initializes a `From` clause with the specified entity class. - Sample Usage: ``` let people = transaction.fetchAll(From()) ``` + - parameter entityClass: the `NSManagedObject` class type to be created */ public init(_ entityClass: AnyClass) { @@ -81,10 +80,10 @@ public struct From { /** Initializes a `From` clause with the specified configurations. - Sample Usage: ``` let people = transaction.fetchAll(From(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 { /** Initializes a `From` clause with the specified configurations. - Sample Usage: ``` let people = transaction.fetchAll(From(["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 { /** 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 { /** 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 { /** 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 { /** 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. */ diff --git a/Sources/Fetching and Querying/Concrete Clauses/Select.swift b/Sources/Fetching and Querying/Concrete Clauses/Select.swift index a7d124b..20c9146 100644 --- a/Sources/Fetching and Querying/Concrete Clauses/Select.swift +++ b/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(.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()" 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(.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()" is used - returns: a `SelectTerm` to a `Select` clause for a count query @@ -143,6 +146,7 @@ public enum SelectTerm: StringLiteralConvertible, Hashable { Select(.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()" 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(.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()" 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(.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()" 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 diff --git a/Sources/Fetching and Querying/Concrete Clauses/Tweak.swift b/Sources/Fetching and Querying/Concrete Clauses/Tweak.swift index 6a56ccc..6427c6f 100644 --- a/Sources/Fetching and Querying/Concrete Clauses/Tweak.swift +++ b/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) { diff --git a/Sources/Logging/CoreStoreLogger.swift b/Sources/Logging/CoreStoreLogger.swift index 3095bd2..367bb57 100644 --- a/Sources/Logging/CoreStoreLogger.swift +++ b/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) diff --git a/Sources/Logging/DefaultLogger.swift b/Sources/Logging/DefaultLogger.swift index dce6ac0..afac6ee 100644 --- a/Sources/Logging/DefaultLogger.swift +++ b/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 diff --git a/Sources/Migrating/CoreStore+Migration.swift b/Sources/Migrating/CoreStore+Migration.swift index da03227..9c9675e 100644 --- a/Sources/Migrating/CoreStore+Migration.swift +++ b/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(storeType: T.Type, completion: (SetupResult) -> 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(storage: T, completion: (SetupResult) -> 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(storeType: T.Type, completion: (SetupResult) -> 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(storage: T, completion: (SetupResult) -> 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(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 diff --git a/Sources/Migrating/DataStack+Migration.swift b/Sources/Migrating/DataStack+Migration.swift index 01fad1a..d5827e4 100644 --- a/Sources/Migrating/DataStack+Migration.swift +++ b/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(storeType: T.Type, completion: (SetupResult) -> 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(storage: T, completion: (SetupResult) -> 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(storeType: T.Type, completion: (SetupResult) -> 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(storage: T, completion: (SetupResult) -> 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(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 diff --git a/Sources/Migrating/MigrationChain.swift b/Sources/Migrating/MigrationChain.swift index ce6570a..524e4b9 100644 --- a/Sources/Migrating/MigrationChain.swift +++ b/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(_ 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 }) diff --git a/Sources/ObjectiveC/CSAsynchronousDataTransaction.swift b/Sources/ObjectiveC/CSAsynchronousDataTransaction.swift index fd08662..a4bd294 100644 --- a/Sources/ObjectiveC/CSAsynchronousDataTransaction.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSBaseDataTransaction.swift b/Sources/ObjectiveC/CSBaseDataTransaction.swift index 3d4b666..ca1f6ca 100644 --- a/Sources/ObjectiveC/CSBaseDataTransaction.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSClauseTypes.swift b/Sources/ObjectiveC/CSClauseTypes.swift index b48fe86..b622687 100644 --- a/Sources/ObjectiveC/CSClauseTypes.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSCoreStore+Migrating.swift b/Sources/ObjectiveC/CSCoreStore+Migrating.swift index bff4a9b..198ce92 100644 --- a/Sources/ObjectiveC/CSCoreStore+Migrating.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSCoreStore+Setup.swift b/Sources/ObjectiveC/CSCoreStore+Setup.swift index 4642275..1550371 100644 --- a/Sources/ObjectiveC/CSCoreStore+Setup.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSCoreStore.swift b/Sources/ObjectiveC/CSCoreStore.swift index 758fdd7..1d552af 100644 --- a/Sources/ObjectiveC/CSCoreStore.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSDataStack+Migrating.swift b/Sources/ObjectiveC/CSDataStack+Migrating.swift index 9f99080..c899c83 100644 --- a/Sources/ObjectiveC/CSDataStack+Migrating.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSDataStack.swift b/Sources/ObjectiveC/CSDataStack.swift index 1a36694..8b479e2 100644 --- a/Sources/ObjectiveC/CSDataStack.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSError.swift b/Sources/ObjectiveC/CSError.swift index a7a9cf4..ab8c543 100644 --- a/Sources/ObjectiveC/CSError.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSFrom.swift b/Sources/ObjectiveC/CSFrom.swift index e793d8f..abe6ada 100644 --- a/Sources/ObjectiveC/CSFrom.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSGroupBy.swift b/Sources/ObjectiveC/CSGroupBy.swift index 43dd025..031a570 100644 --- a/Sources/ObjectiveC/CSGroupBy.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSInMemoryStore.swift b/Sources/ObjectiveC/CSInMemoryStore.swift index 3539c7f..c092588 100644 --- a/Sources/ObjectiveC/CSInMemoryStore.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSInto.swift b/Sources/ObjectiveC/CSInto.swift index e79a318..b2ee480 100644 --- a/Sources/ObjectiveC/CSInto.swift +++ b/Sources/ObjectiveC/CSInto.swift @@ -31,6 +31,8 @@ import CoreData /** The `CSInto` serves as the Objective-C bridging type for `Into`. + + - 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 diff --git a/Sources/ObjectiveC/CSListMonitor.swift b/Sources/ObjectiveC/CSListMonitor.swift index a0d03b2..f142aac 100644 --- a/Sources/ObjectiveC/CSListMonitor.swift +++ b/Sources/ObjectiveC/CSListMonitor.swift @@ -31,6 +31,8 @@ import CoreData /** The `CSListMonitor` serves as the Objective-C bridging type for `ListMonitor`. + + - SeeAlso: `ListMonitor` */ @available(OSX, unavailable) @objc diff --git a/Sources/ObjectiveC/CSListObserver.swift b/Sources/ObjectiveC/CSListObserver.swift index 02a5f96..f59909d 100644 --- a/Sources/ObjectiveC/CSListObserver.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSMigrationResult.swift b/Sources/ObjectiveC/CSMigrationResult.swift index 727c4c7..f9c2962 100644 --- a/Sources/ObjectiveC/CSMigrationResult.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSMigrationType.swift b/Sources/ObjectiveC/CSMigrationType.swift index 4790566..35b98ef 100644 --- a/Sources/ObjectiveC/CSMigrationType.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSObjectMonitor.swift b/Sources/ObjectiveC/CSObjectMonitor.swift index 3be81a5..5cb890b 100644 --- a/Sources/ObjectiveC/CSObjectMonitor.swift +++ b/Sources/ObjectiveC/CSObjectMonitor.swift @@ -31,6 +31,8 @@ import CoreData /** The `CSObjectMonitor` serves as the Objective-C bridging type for `ObjectMonitor`. + + - SeeAlso: `ObjectMonitor` */ @available(OSX, unavailable) @objc diff --git a/Sources/ObjectiveC/CSObjectObserver.swift b/Sources/ObjectiveC/CSObjectObserver.swift index 2b6e079..46eba1f 100644 --- a/Sources/ObjectiveC/CSObjectObserver.swift +++ b/Sources/ObjectiveC/CSObjectObserver.swift @@ -35,6 +35,8 @@ import CoreData CSObjectMonitor *monitor = [CSCoreStore monitorObject:myObject]; [monitor addObjectObserver:self]; ``` + + - SeeAlso: `ObjectObserver` */ @available(OSX, unavailable) @objc diff --git a/Sources/ObjectiveC/CSOrderBy.swift b/Sources/ObjectiveC/CSOrderBy.swift index fa447e1..51ee2c7 100644 --- a/Sources/ObjectiveC/CSOrderBy.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSSQliteStore.swift b/Sources/ObjectiveC/CSSQliteStore.swift index e0d2ce8..061730c 100644 --- a/Sources/ObjectiveC/CSSQliteStore.swift +++ b/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/" 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 @@ -80,6 +82,7 @@ public final class CSSQLiteStore: NSObject, CSLocalStorage, CoreStoreObjectiveCT /** Initializes an `CSSQLiteStore` with an all-default settings: a `fileURL` pointing to a ".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 `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) } diff --git a/Sources/ObjectiveC/CSSaveResult.swift b/Sources/ObjectiveC/CSSaveResult.swift index 28d03e0..a764de3 100644 --- a/Sources/ObjectiveC/CSSaveResult.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSSectionBy.swift b/Sources/ObjectiveC/CSSectionBy.swift index d8b6835..bd89f09 100644 --- a/Sources/ObjectiveC/CSSectionBy.swift +++ b/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 diff --git a/Sources/ObjectiveC/CSSelect.swift b/Sources/ObjectiveC/CSSelect.swift index 4f8b0d4..415e834 100644 --- a/Sources/ObjectiveC/CSSelect.swift +++ b/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()" 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()" 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()" 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()" 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()" 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(.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(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(terms.map { $0.bridgeToSwift })) diff --git a/Sources/ObjectiveC/CSSetupResult.swift b/Sources/ObjectiveC/CSSetupResult.swift index 9766f0c..d47914f 100644 --- a/Sources/ObjectiveC/CSSetupResult.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSStorageInterface.swift b/Sources/ObjectiveC/CSStorageInterface.swift index 0a15e49..9696d8f 100644 --- a/Sources/ObjectiveC/CSStorageInterface.swift +++ b/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 } diff --git a/Sources/ObjectiveC/CSSynchronousDataTransaction.swift b/Sources/ObjectiveC/CSSynchronousDataTransaction.swift index 3c55143..4da33be 100644 --- a/Sources/ObjectiveC/CSSynchronousDataTransaction.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSTweak.swift b/Sources/ObjectiveC/CSTweak.swift index fd65532..c867524 100644 --- a/Sources/ObjectiveC/CSTweak.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSUnsafeDataTransaction.swift b/Sources/ObjectiveC/CSUnsafeDataTransaction.swift index 3395d63..2f0c5e7 100644 --- a/Sources/ObjectiveC/CSUnsafeDataTransaction.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CSWhere.swift b/Sources/ObjectiveC/CSWhere.swift index 5008ca4..d227164 100644 --- a/Sources/ObjectiveC/CSWhere.swift +++ b/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 { diff --git a/Sources/ObjectiveC/CoreStoreBridge.swift b/Sources/ObjectiveC/CoreStoreBridge.swift index 40718fb..907125e 100644 --- a/Sources/ObjectiveC/CoreStoreBridge.swift +++ b/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(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(error: NSErrorPointer, @noescape _ closure: () throws -> T?) -> T? { do { diff --git a/Sources/ObjectiveC/NSFetchedResultsController+ObjectiveC.swift b/Sources/ObjectiveC/NSFetchedResultsController+ObjectiveC.swift index 6f2725b..d02fab5 100644 --- a/Sources/ObjectiveC/NSFetchedResultsController+ObjectiveC.swift +++ b/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 { diff --git a/Sources/ObjectiveC/NSProgress+ObjectiveC.swift b/Sources/ObjectiveC/NSProgress+ObjectiveC.swift index d09ae10..ee2c93c 100644 --- a/Sources/ObjectiveC/NSProgress+ObjectiveC.swift +++ b/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 diff --git a/Sources/Observing/SectionBy.swift b/Sources/Observing/SectionBy.swift index 5f4621f..97d307f 100644 --- a/Sources/Observing/SectionBy.swift +++ b/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 */ diff --git a/Sources/Saving and Processing/Into.swift b/Sources/Saving and Processing/Into.swift index 5ff660b..6384fac 100644 --- a/Sources/Saving and Processing/Into.swift +++ b/Sources/Saving and Processing/Into.swift @@ -43,7 +43,6 @@ public struct Into: Hashable { /** Initializes an `Into` clause. - Sample Usage: ``` let person = transaction.create(Into()) ``` @@ -55,10 +54,10 @@ public struct Into: 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: 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: Hashable { /** Initializes an `Into` clause with the specified configuration. - Sample Usage: ``` let person = transaction.create(Into("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: 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: 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. */ diff --git a/Sources/Saving and Processing/NSManagedObject+Transaction.swift b/Sources/Saving and Processing/NSManagedObject+Transaction.swift index 88374d9..f26279e 100644 --- a/Sources/Saving and Processing/NSManagedObject+Transaction.swift +++ b/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? { diff --git a/Sources/Saving and Processing/UnsafeDataTransaction.swift b/Sources/Saving and Processing/UnsafeDataTransaction.swift index e12eacf..6dbb171 100644 --- a/Sources/Saving and Processing/UnsafeDataTransaction.swift +++ b/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. */ diff --git a/Sources/Setup/CoreStore+Setup.swift b/Sources/Setup/CoreStore+Setup.swift index 8f9b9a4..74b8d02 100644 --- a/Sources/Setup/CoreStore+Setup.swift +++ b/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(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(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(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(storage: T) throws -> T { diff --git a/Sources/Setup/DataStack.swift b/Sources/Setup/DataStack.swift index 0a900a5..8e35795 100644 --- a/Sources/Setup/DataStack.swift +++ b/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(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(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(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(storage: T) throws -> T { diff --git a/Sources/Setup/StorageInterfaces/InMemoryStore.swift b/Sources/Setup/StorageInterfaces/InMemoryStore.swift index 0406ea6..30d1a82 100644 --- a/Sources/Setup/StorageInterfaces/InMemoryStore.swift +++ b/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?) { diff --git a/Sources/Setup/StorageInterfaces/LegacySQLiteStore.swift b/Sources/Setup/StorageInterfaces/LegacySQLiteStore.swift index 5b8a296..feae4c5 100644 --- a/Sources/Setup/StorageInterfaces/LegacySQLiteStore.swift +++ b/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 ".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() { diff --git a/Sources/Setup/StorageInterfaces/SQLiteStore.swift b/Sources/Setup/StorageInterfaces/SQLiteStore.swift index 8f8ddbf..294e01c 100644 --- a/Sources/Setup/StorageInterfaces/SQLiteStore.swift +++ b/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/" 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 @@ -73,6 +74,7 @@ public final class SQLiteStore: LocalStorage, DefaultInitializableStore { /** Initializes an `SQLiteStore` with an all-default settings: a `fileURL` pointing to a ".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() { diff --git a/Sources/Setup/StorageInterfaces/StorageInterface.swift b/Sources/Setup/StorageInterfaces/StorageInterface.swift index 6d64126..b6dd6dc 100644 --- a/Sources/Setup/StorageInterfaces/StorageInterface.swift +++ b/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 }