diff --git a/CoreStore.xcodeproj/project.pbxproj b/CoreStore.xcodeproj/project.pbxproj index e4ed3f4..551ec82 100644 --- a/CoreStore.xcodeproj/project.pbxproj +++ b/CoreStore.xcodeproj/project.pbxproj @@ -2501,6 +2501,7 @@ CLANG_WARN_BOOL_CONVERSION = YES; CLANG_WARN_CONSTANT_CONVERSION = YES; CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_EMPTY_BODY = YES; CLANG_WARN_ENUM_CONVERSION = YES; CLANG_WARN_INFINITE_RECURSION = YES; @@ -2559,6 +2560,7 @@ CLANG_WARN_BOOL_CONVERSION = YES; CLANG_WARN_CONSTANT_CONVERSION = YES; CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR; + CLANG_WARN_DOCUMENTATION_COMMENTS = YES; CLANG_WARN_EMPTY_BODY = YES; CLANG_WARN_ENUM_CONVERSION = YES; CLANG_WARN_INFINITE_RECURSION = YES; diff --git a/Sources/CSAsynchronousDataTransaction.swift b/Sources/CSAsynchronousDataTransaction.swift index dcba279..7089941 100644 --- a/Sources/CSAsynchronousDataTransaction.swift +++ b/Sources/CSAsynchronousDataTransaction.swift @@ -40,7 +40,8 @@ public final class CSAsynchronousDataTransaction: CSBaseDataTransaction { /** Saves the transaction changes. This method should not be used after the `-commitWithCompletion:` method was already called once. - - parameter completion: the block executed after the save completes. Success or failure is reported by the `CSSaveResult` argument of the block. + - parameter success: the block executed if the save succeeds. + - parameter failure: the block executed if the save fails. A `CSError` is reported as the argument of the block. */ @objc public func commitWithSuccess(_ success: (() -> Void)?, failure: ((CSError) -> Void)?) { @@ -156,11 +157,6 @@ public final class CSAsynchronousDataTransaction: CSBaseDataTransaction { // MARK: Deprecated - /** - Saves the transaction changes. This method should not be used after the `-commitWithCompletion:` method was already called once. - - - parameter completion: the block executed after the save completes. Success or failure is reported by the `CSSaveResult` argument of the block. - */ @available(*, deprecated, message: "Use the new -[CSAsynchronousDataTransaction commitWithSuccess:failure:] method.") @objc public func commitWithCompletion(_ completion: ((_ result: CSSaveResult) -> Void)?) { @@ -179,12 +175,6 @@ public final class CSAsynchronousDataTransaction: CSBaseDataTransaction { } } - /** - Begins a child transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made. This method should not be used after the `-commitWithCompletion:` method was already called once. - - - parameter closure: the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`. - - returns: a `CSSaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously - */ @available(*, deprecated, message: "Secondary tasks spawned from CSAsynchronousDataTransactions and CSSynchronousDataTransactions are no longer supported. ") @objc @discardableResult diff --git a/Sources/CSBaseDataTransaction.swift b/Sources/CSBaseDataTransaction.swift index d507f95..03d0ad0 100644 --- a/Sources/CSBaseDataTransaction.swift +++ b/Sources/CSBaseDataTransaction.swift @@ -204,7 +204,6 @@ public class CSBaseDataTransaction: NSObject, CoreStoreObjectiveCType { /** Returns all pending `NSManagedObjectID`s of the specified type that were deleted from the transaction. This method should not be called after the `-commit*:` method was called. - - parameter entity: the `NSManagedObject` subclass to filter - returns: an `NSSet` of pending `NSManagedObjectID`s of the specified type that were deleted from the transaction. */ @objc diff --git a/Sources/CSCoreStore+Setup.swift b/Sources/CSCoreStore+Setup.swift index 2521dd0..440478b 100644 --- a/Sources/CSCoreStore+Setup.swift +++ b/Sources/CSCoreStore+Setup.swift @@ -129,9 +129,6 @@ public extension CSCoreStore { // MARK: Deprecated - /** - Returns the entity name-to-class type mapping from the `defaultStack`'s model. - */ @available(*, deprecated, message: "Use the new +entityTypesByNameForType: method passing `[NSManagedObject class]` as argument.") @objc public static var entityClassesByName: [EntityName: NSManagedObject.Type] { @@ -139,12 +136,6 @@ public extension CSCoreStore { return CoreStore.entityTypesByName } - /** - 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 - */ @available(*, deprecated, message: "Use the new +entityTypesByNameForType: method passing `[NSManagedObject class]` as argument.") @objc public static func entityClassWithName(_ name: EntityName) -> NSManagedObject.Type? { diff --git a/Sources/CSCoreStore+Transaction.swift b/Sources/CSCoreStore+Transaction.swift index 2c2f8a0..ad19038 100644 --- a/Sources/CSCoreStore+Transaction.swift +++ b/Sources/CSCoreStore+Transaction.swift @@ -95,12 +95,6 @@ public extension CSCoreStore { // MARK: Deprecated - /** - Using the `defaultStack`, begins a transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made. - - - parameter closure: the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`. - - returns: a `CSSaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously - */ @available(*, deprecated, message: "Use the new +[CSCoreStore beginSynchronous:error:] API that reports failure using an error instance.") @objc @discardableResult diff --git a/Sources/CSDataStack+Transaction.swift b/Sources/CSDataStack+Transaction.swift index b6f161e..0a8e90d 100644 --- a/Sources/CSDataStack+Transaction.swift +++ b/Sources/CSDataStack+Transaction.swift @@ -135,12 +135,6 @@ public extension CSDataStack { // MARK: Deprecated - /** - Begins a transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made. - - - parameter closure: the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`. - - returns: a `CSSaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously - */ @available(*, deprecated, message: "Use the new -[CSDataStack beginSynchronous:error:] API that reports failure using an error instance.") @objc @discardableResult diff --git a/Sources/CSDataStack.swift b/Sources/CSDataStack.swift index e683f6d..da8614d 100644 --- a/Sources/CSDataStack.swift +++ b/Sources/CSDataStack.swift @@ -227,12 +227,6 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType { // MARK: Deprecated - /** - Initializes a `DataStack` from an `NSManagedObjectModel`. - - - parameter model: the `NSManagedObjectModel` for the stack - - parameter versionChain: the `MigrationChain` that indicates the sequence of model versions to be used as the order for progressive migrations. If not specified, will default to a non-migrating data stack. - */ @available(*, deprecated, message: "Use the -[initWithModelName:bundle:versionChain:] initializer.") @objc public convenience init(model: NSManagedObjectModel, versionChain: [String]?) { @@ -245,12 +239,6 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType { ) } - /** - Initializes a `DataStack` from an `NSManagedObjectModel`. - - - parameter model: the `NSManagedObjectModel` for the stack - - parameter versionTree: the `MigrationChain` that indicates the sequence of model versions to be used as the order for progressive migrations. If not specified, will default to a non-migrating data stack. - */ @available(*, deprecated, message: "Use the -[initWithModelName:bundle:versionTree:] initializer.") @objc public convenience init(model: NSManagedObjectModel, versionTree: [String]?) { @@ -263,9 +251,6 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType { ) } - /** - Returns the entity name-to-class type mapping from the stack's model. - */ @available(*, deprecated, message: "Use the new -entityTypesByNameForType: method passing `[NSManagedObject class]` as argument.") @objc public var entityClassesByName: [EntityName: NSManagedObject.Type] { @@ -273,11 +258,6 @@ public final class CSDataStack: NSObject, CoreStoreObjectiveCType { return self.bridgeToSwift.entityTypesByName } - /** - Returns the entity class for the given entity name from the stack's's model. - - parameter name: the entity name - - returns: the `NSManagedObject` class for the given entity name, or `nil` if not found - */ @available(*, deprecated, message: "Use the new -entityTypesByNameForType: method passing `[NSManagedObject class]` as argument.") @objc public func entityClassWithName(_ name: EntityName) -> NSManagedObject.Type? { diff --git a/Sources/CSFrom.swift b/Sources/CSFrom.swift index 0c913ec..fca0c17 100644 --- a/Sources/CSFrom.swift +++ b/Sources/CSFrom.swift @@ -82,6 +82,7 @@ public final class CSFrom: NSObject { MyPersonEntity *people = [transaction fetchAllFrom: CSFromClass([MyPersonEntity class], @"Config1")]; ``` + - parameter entityClass: 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 `[NSNull null]` to use the default configuration. */ @objc @@ -107,7 +108,7 @@ public final class CSFrom: NSObject { CSFromClass([MyPersonEntity class], @[[NSNull null], @"Config1"])]; ``` - - parameter entity: the associated `NSManagedObject` entity class + - parameter entityClass: the associated `NSManagedObject` entity class - parameter configurations: an array of the `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. */ @objc diff --git a/Sources/CSSaveResult.swift b/Sources/CSSaveResult.swift index 7f0fcbd..d1263bb 100644 --- a/Sources/CSSaveResult.swift +++ b/Sources/CSSaveResult.swift @@ -29,36 +29,22 @@ import CoreData // MARK: - CSSaveResult -/** - The `CSSaveResult` serves as the Objective-C bridging type for `SaveResult`. - - - SeeAlso: `SaveResult` - */ @available(*, deprecated, message: "Use APIs that report failures with `CSError`s instead.") @objc public final class CSSaveResult: NSObject, CoreStoreObjectiveCType { - /** - `YES` if the `commit` operation for the transaction succeeded, either because the save succeeded or because there were no changes to save. Returns `NO` to indicate failure. - */ @objc public var isSuccess: Bool { return self.bridgeToSwift.boolValue } - /** - `YES` if the `commit` operation for the transaction failed, or `NO` otherwise. When `YES`, the `error` property returns the actual `NSError` for the failure. - */ @objc public var isFailure: Bool { return !self.bridgeToSwift.boolValue } - /** - `YES` if the `commit` operation for the transaction succeeded and if there was an actual change made. Returns `NO` otherwise. - */ @objc public var hasChanges: Bool { @@ -69,9 +55,6 @@ public final class CSSaveResult: NSObject, CoreStoreObjectiveCType { return hasChanges } - /** - The `NSError` for a failed `commit` operation, or `nil` if the `commit` succeeded - */ @objc public var error: NSError? { @@ -82,14 +65,6 @@ public final class CSSaveResult: NSObject, CoreStoreObjectiveCType { return error.bridgeToObjectiveC } - /** - If the result was a success, the `success` block is executed with a `BOOL` argument that indicates if there were any changes made. If the result was a failure, the `failure` block is executed with an `NSError` argument pertaining to the actual error. - - The blocks are executed immediately as `@noescape` and will not be retained. - - - parameter success: the block to execute on success. The block passes a `BOOL` argument that indicates if there were any changes made. - - parameter failure: the block to execute on failure. The block passes an `NSError` argument that pertains to the actual error. - */ @objc public func handleSuccess(_ success: (_ hasChanges: Bool) -> Void, failure: (_ error: NSError) -> Void) { @@ -103,13 +78,6 @@ public final class CSSaveResult: NSObject, CoreStoreObjectiveCType { } } - /** - If the result was a success, the `success` block is executed with a `BOOL` argument that indicates if there were any changes made. If the result was a failure, this method does nothing. - - The block is executed immediately as `@noescape` and will not be retained. - - - parameter success: the block to execute on success. The block passes a `BOOL` argument that indicates if there were any changes made. - */ @objc public func handleSuccess(_ success: (_ hasChanges: Bool) -> Void) { @@ -120,13 +88,6 @@ public final class CSSaveResult: NSObject, CoreStoreObjectiveCType { success(hasChanges) } - /** - If the result was a failure, the `failure` block is executed with an `NSError` argument pertaining to the actual error. If the result was a success, this method does nothing. - - The block is executed immediately as `@noescape` and will not be retained. - - - parameter failure: the block to execute on failure. The block passes an `NSError` argument that pertains to the actual error. - */ @objc public func handleFailure(_ failure: (_ error: NSError) -> Void) { diff --git a/Sources/CSSelect.swift b/Sources/CSSelect.swift index 785413b..74fa947 100644 --- a/Sources/CSSelect.swift +++ b/Sources/CSSelect.swift @@ -146,7 +146,6 @@ public final class CSSelectTerm: NSObject, CoreStoreObjectiveCType { select:[CSSelect objectIDForTerm:[CSSelectTerm objectIDAs:nil]] fetchClauses:@[[CSWhere keyPath:@"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 */ @@ -217,7 +216,7 @@ public final class CSSelect: NSObject { select:CSSelectNumber(CSAggregateMax(@"age")) // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query + - parameter numberTerm: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(numberTerm: CSSelectTerm) { @@ -232,7 +231,7 @@ public final class CSSelect: NSObject { select:CSSelectDecimal(CSAggregateAverage(@"price")) // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query + - parameter decimalTerm: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(decimalTerm: CSSelectTerm) { @@ -247,7 +246,7 @@ public final class CSSelect: NSObject { select:CSSelectString(CSAttribute(@"fullname")) // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query + - parameter stringTerm: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(stringTerm: CSSelectTerm) { @@ -262,7 +261,7 @@ public final class CSSelect: NSObject { select:CSSelectDate(CSAggregateMax(@"updatedDate")) // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query + - parameter dateTerm: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(dateTerm: CSSelectTerm) { @@ -277,7 +276,7 @@ public final class CSSelect: NSObject { select:CSSelectData(CSAttribute(@"imageData")) // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query + - parameter dataTerm: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(dataTerm: CSSelectTerm) { @@ -292,7 +291,6 @@ public final class CSSelect: NSObject { select:CSSelectObjectID() // ... ``` - - parameter term: the `CSSelectTerm` specifying the attribute/aggregate value to query */ public convenience init(objectIDTerm: ()) { diff --git a/Sources/CSSynchronousDataTransaction.swift b/Sources/CSSynchronousDataTransaction.swift index 747008b..5f44a70 100644 --- a/Sources/CSSynchronousDataTransaction.swift +++ b/Sources/CSSynchronousDataTransaction.swift @@ -147,11 +147,6 @@ public final class CSSynchronousDataTransaction: CSBaseDataTransaction { // MARK: Deprecated - /** - Saves the transaction changes and waits for completion synchronously. This method should not be used after the `-commitAndWait` method was already called once. - - - returns: a `CSSaveResult` containing the success or failure information - */ @available(*, deprecated, message: "Use the new -[CSSynchronousDataTransaction commitAndWaitWithError:] method") @objc public func commitAndWait() -> CSSaveResult { @@ -162,12 +157,6 @@ public final class CSSynchronousDataTransaction: CSBaseDataTransaction { } } - /** - Begins a child transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made. This method should not be used after the `-commitAndWait` method was already called once. - - - parameter closure: the block where creates, updates, and deletes can be made to the transaction. Transaction blocks are executed serially in a background queue, and all changes are made from a concurrent `NSManagedObjectContext`. - - returns: a `CSSaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously - */ @available(*, deprecated, message: "Secondary tasks spawned from CSAsynchronousDataTransactions and CSSynchronousDataTransactions are no longer supported. ") @objc @discardableResult diff --git a/Sources/CSUnsafeDataTransaction.swift b/Sources/CSUnsafeDataTransaction.swift index beba7ce..e0f0ee7 100644 --- a/Sources/CSUnsafeDataTransaction.swift +++ b/Sources/CSUnsafeDataTransaction.swift @@ -39,7 +39,8 @@ public final class CSUnsafeDataTransaction: CSBaseDataTransaction { /** Saves the transaction changes asynchronously. For a `CSUnsafeDataTransaction`, multiple commits are allowed, although it is the developer's responsibility to ensure a reasonable leeway to prevent blocking the main thread. - - parameter completion: the block executed after the save completes. Success or failure is reported by the `error` argument of the block. + - parameter success: the block executed if the save succeeds. + - parameter failure: the block executed if the save fails. A `CSError` is reported as the argument of the block. */ @objc public func commitWithSuccess(_ success: (() -> Void)?, _ failure: ((CSError) -> Void)?) { @@ -118,7 +119,7 @@ public final class CSUnsafeDataTransaction: CSBaseDataTransaction { Flushes all pending changes to the transaction's observers at the end of the `closure`'s execution. This is useful in conjunction with `ListMonitor`s and `ObjectMonitor`s created from `UnsafeDataTransaction`s used to manage temporary "scratch" data. - Important: Note that unlike `commit()`, `flush()` does not propagate/save updates to the `DataStack` and the persistent store. However, the flushed changes will be seen by children transactions created further from the current transaction (i.e. through `transaction.beginUnsafe()`) - - parameter closure: the closure where changes can be made prior to the flush + - parameter block: the block where changes can be made prior to the flush */ @objc public func flush(_ block: () -> Void) { @@ -210,11 +211,6 @@ public final class CSUnsafeDataTransaction: CSBaseDataTransaction { return self.bridgeToSwift.context } - /** - Saves the transaction changes asynchronously. For a `CSUnsafeDataTransaction`, multiple commits are allowed, although it is the developer's responsibility to ensure a reasonable leeway to prevent blocking the main thread. - - - parameter completion: the block executed after the save completes. Success or failure is reported by the `CSSaveResult` argument of the block. - */ @available(*, deprecated, message: "Use the new -[CSUnsafeDataTransaction commitWithSuccess:failure:] method") @objc public func commit(_ completion: ((_ result: CSSaveResult) -> Void)?) { @@ -233,11 +229,6 @@ public final class CSUnsafeDataTransaction: CSBaseDataTransaction { } } - /** - Saves the transaction changes and waits for completion synchronously. For a `CSUnsafeDataTransaction`, multiple commits are allowed, although it is the developer's responsibility to ensure a reasonable leeway to prevent blocking the main thread. - - - returns: a `CSSaveResult` containing the success or failure information - */ @available(*, deprecated, message: "Use the new -[CSUnsafeDataTransaction commitAndWaitWithError:] method") @objc public func commitAndWait() -> CSSaveResult { diff --git a/Sources/CoreStore+Setup.swift b/Sources/CoreStore+Setup.swift index e2c6e68..2330c40 100644 --- a/Sources/CoreStore+Setup.swift +++ b/Sources/CoreStore+Setup.swift @@ -143,9 +143,6 @@ public extension CoreStore { // MARK: Deprecated - /** - Returns the entity name-to-class type mapping from the `defaultStack`'s model. - */ @available(*, deprecated, message: "Use the new CoreStore.entityTypesByName(for:) method passing `NSManagedObject.self` as argument.") public static var entityTypesByName: [EntityName: NSManagedObject.Type] { diff --git a/Sources/CoreStoreBridge.h b/Sources/CoreStoreBridge.h index e685223..9af4fe2 100644 --- a/Sources/CoreStoreBridge.h +++ b/Sources/CoreStoreBridge.h @@ -156,7 +156,7 @@ CSFrom *_Nonnull CSFromClass(Class _Nonnull entityClass, NSArray *_Nonnull c @abstract Initializes a CSGroupBy clause with a key path string - @param keyPaths + @param keyPath a key path string to group results with @result @@ -169,7 +169,7 @@ CSGroupBy *_Nonnull CSGroupByKeyPath(NSString *_Nonnull keyPath) CORESTORE_RETUR @abstract Initializes a CSGroupBy clause with a list of key path strings - @param keyPaths + @param keyPath a nil-terminated list of key path strings to group results with @result @@ -328,7 +328,7 @@ CSOrderBy *_Nonnull CSOrderByKey(NSSortDescriptor *_Nonnull sortDescriptor) CORE fetchClauses:@[CSOrderByKeys(CSSortAscending(@"fullname"), CSSortDescending(@"age"), nil))]]]; @endcode - @param sortDescriptors + @param sortDescriptor a nil-terminated array of NSSortDescriptors @result @@ -473,9 +473,6 @@ CSSelect *_Nonnull CSSelectData(CSSelectTerm *_Nonnull selectTerm) CORESTORE_RET // ... @endcode - @param selectTerm - the CSSelectTerm specifying the attribute/aggregate value to query - @result a CSSelect clause for querying an NSManagedObjectID value */ @@ -538,10 +535,7 @@ CSWhere *_Nonnull CSWhereValue(BOOL value) CORESTORE_RETURNS_RETAINED; @endcode @param format - the format string for the predicate - - @param argumentArray - the arguments for format + the format string for the predicate, followed by an optional comma-separated argument list @result a CSWhere clause with a predicate using the specified string format and arguments diff --git a/Sources/DataStack.swift b/Sources/DataStack.swift index 5f50df4..74ba992 100644 --- a/Sources/DataStack.swift +++ b/Sources/DataStack.swift @@ -613,12 +613,6 @@ public final class DataStack: Equatable { // MARK: Deprecated - /** - Initializes a `DataStack` from an `NSManagedObjectModel`. - - - parameter model: the `NSManagedObjectModel` for the stack - - parameter migrationChain: the `MigrationChain` that indicates the sequence of model versions to be used as the order for progressive migrations. If not specified, will default to a non-migrating data stack. - */ @available(*, deprecated, message: "Use the new DataStack.init(schemaHistory:) initializer passing a LegacyXcodeDataModelSchema instance as argument") public convenience init(model: NSManagedObjectModel, migrationChain: MigrationChain = nil) { @@ -637,9 +631,6 @@ public final class DataStack: Equatable { ) } - /** - Returns the entity name-to-class type mapping from the `DataStack`'s model. - */ @available(*, deprecated, message: "Use the new DataStack.entityTypesByName(for:) method passing `NSManagedObject.self` as argument.") public var entityTypesByName: [EntityName: NSManagedObject.Type] { diff --git a/Sources/NSFetchedResultsController+ObjectiveC.swift b/Sources/NSFetchedResultsController+ObjectiveC.swift index cdfc870..f37b06a 100644 --- a/Sources/NSFetchedResultsController+ObjectiveC.swift +++ b/Sources/NSFetchedResultsController+ObjectiveC.swift @@ -32,15 +32,6 @@ import CoreData @available(OSX 10.12, *) public extension CSDataStack { - /** - Utility for creating an `NSFetchedResultsController` from the `CSDataStack`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `CSListMonitor`s abstraction. - - Note: It is the caller's responsibility to call `-performFetch:` on the created `NSFetchedResultsController`. - - - parameter from: a `CSFrom` clause indicating the entity type - - parameter sectionBy: a `CSSectionBy` clause indicating the keyPath for the attribute to use when sorting the list into sections. - - parameter fetchClauses: a series of `CSFetchClause` instances for fetching the object list. Accepts `CSWhere`, `CSOrderBy`, and `CSTweak` clauses. - - returns: an `NSFetchedResultsController` that observes the `CSDataStack` - */ @available(*, deprecated, message: "CoreStore will obsolete NSFetchedResultsController support in the future in favor of CSListMonitor") @objc public func createFetchedResultsControllerFrom(_ from: CSFrom, sectionBy: CSSectionBy, fetchClauses: [CSFetchClause]) -> NSFetchedResultsController { @@ -60,15 +51,6 @@ public extension CSDataStack { @available(OSX 10.12, *) public extension CSUnsafeDataTransaction { - /** - Utility for creating an `NSFetchedResultsController` from the `CSUnsafeDataTransaction`. This is useful when an `NSFetchedResultsController` is preferred over the overhead of `CSListMonitor`s abstraction. - - Note: It is the caller's responsibility to call `-performFetch:` on the created `NSFetchedResultsController`. - - - parameter from: a `CSFrom` clause indicating the entity type - - 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 `Where`, `OrderBy`, and `Tweak` clauses. - - returns: an `NSFetchedResultsController` that observes an `CSUnsafeDataTransaction` - */ @available(*, deprecated, message: "CoreStore will obsolete NSFetchedResultsController support in the future in favor of CSListMonitor") @objc public func createFetchedResultsControllerFrom(_ from: CSFrom, sectionBy: CSSectionBy, fetchClauses: [CSFetchClause]) -> NSFetchedResultsController { diff --git a/Sources/NSManagedObject+Convenience.swift b/Sources/NSManagedObject+Convenience.swift index 9dd3256..f9d206c 100644 --- a/Sources/NSManagedObject+Convenience.swift +++ b/Sources/NSManagedObject+Convenience.swift @@ -77,6 +77,12 @@ public extension NSManagedObject { return context } + /** + Provides a convenience wrapper for accessing `primitiveValue(forKey:)` with proper calls to `willAccessValue(forKey:)` and `didAccessValue(forKey:)`. This is useful when implementing accessor methods for transient attributes. + + - parameter kvcKey: the KVC key + - returns: the primitive value for the KVC key + */ @nonobjc @inline(__always) public func getValue(forKvcKey kvcKey: KeyPath) -> Any? { @@ -88,6 +94,13 @@ public extension NSManagedObject { return self.primitiveValue(forKey: kvcKey) } + /** + Provides a convenience wrapper for accessing `primitiveValue(forKey:)` with proper calls to `willAccessValue(forKey:)` and `didAccessValue(forKey:)`. This is useful when implementing accessor methods for transient attributes. + + - parameter kvcKey: the KVC key + - parameter didGetValue: a closure to transform the primitive value + - returns: the primitive value transformed by the `didGetValue` closure + */ @nonobjc @inline(__always) public func getValue(forKvcKey kvcKey: KeyPath, didGetValue: (Any?) throws -> T) rethrows -> T { @@ -99,6 +112,14 @@ public extension NSManagedObject { return try didGetValue(self.primitiveValue(forKey: kvcKey)) } + /** + Provides a convenience wrapper for accessing `primitiveValue(forKey:)` with proper calls to `willAccessValue(forKey:)` and `didAccessValue(forKey:)`. This is useful when implementing accessor methods for transient attributes. + + - parameter kvcKey: the KVC key + - parameter willGetValue: called before accessing `primitiveValue(forKey:)`. Callers are allowed to cancel the access by throwing an error. + - parameter didGetValue: a closure to transform the primitive value + - returns: the primitive value transformed by the `didGetValue` closure + */ @nonobjc @inline(__always) public func getValue(forKvcKey kvcKey: KeyPath, willGetValue: () throws -> Void, didGetValue: (Any?) throws -> T) rethrows -> T { @@ -111,6 +132,12 @@ public extension NSManagedObject { return try didGetValue(self.primitiveValue(forKey: kvcKey)) } + /** + Provides a convenience wrapper for setting `setPrimitiveValue(_:forKey:)` with proper calls to `willChangeValue(forKey:)` and `didChangeValue(forKey:)`. This is useful when implementing mutator methods for transient attributes. + + - parameter value: the value to set the KVC key with + - parameter KVCKey: the KVC key + */ @nonobjc @inline(__always) public func setValue(_ value: Any?, forKvcKey KVCKey: KeyPath) { @@ -122,6 +149,13 @@ public extension NSManagedObject { self.setPrimitiveValue(value, forKey: KVCKey) } + /** + Provides a convenience wrapper for setting `setPrimitiveValue(_:forKey:)` with proper calls to `willChangeValue(forKey:)` and `didChangeValue(forKey:)`. This is useful when implementing mutator methods for transient attributes. + + - parameter value: the value to set the KVC key with + - parameter KVCKey: the KVC key + - parameter willSetValue: called before accessing `setPrimitiveValue(forKey:)`. Callers are allowed to cancel the mutation by throwing an error, for example, for custom validations. + */ @nonobjc @inline(__always) public func setValue(_ value: T, forKvcKey KVCKey: KeyPath, willSetValue: (T) throws -> Any?) rethrows { @@ -154,12 +188,6 @@ public extension NSManagedObject { // MARK: Deprecated - /** - Provides a convenience wrapper for accessing `primitiveValueForKey(...)` with proper calls to `willAccessValueForKey(...)` and `didAccessValueForKey(...)`. This is useful when implementing accessor methods for transient attributes. - - - parameter KVCKey: the KVC key - - returns: the primitive value for the KVC key - */ @available(*, deprecated, renamed: "getValue(forKvcKey:)") @nonobjc public func accessValueForKVCKey(_ KVCKey: KeyPath) -> Any? { @@ -172,13 +200,6 @@ public extension NSManagedObject { return self.primitiveValue(forKey: KVCKey) } - /** - Provides a convenience wrapper for accessing `primitiveValueForKey(...)` with proper calls to `willAccessValueForKey(...)` and `didAccessValueForKey(...)`. This is useful when implementing accessor methods for transient attributes. - - - parameter KVCKey: the KVC key - - parameter didAccessPrimitiveValue: the closure to access the value. This is called between `willAccessValueForKey(...)` and `didAccessValueForKey(...)` - - returns: the primitive value for the KVC key - */ @available(*, deprecated, renamed: "getValue(forKvcKey:didGetValue:)") @discardableResult @nonobjc @@ -192,12 +213,6 @@ public extension NSManagedObject { return try didAccessPrimitiveValue(self.primitiveValue(forKey: KVCKey)) } - /** - Provides a convenience wrapper for setting `setPrimitiveValue(...)` with proper calls to `willChangeValueForKey(...)` and `didChangeValueForKey(...)`. This is useful when implementing mutator methods for transient attributes. - - - parameter value: the value to set the KVC key with - - parameter KVCKey: the KVC key - */ @available(*, deprecated, renamed: "setValue(_:forKvcKey:)") @nonobjc public func setValue(_ value: Any?, forKVCKey KVCKey: KeyPath) { @@ -210,13 +225,6 @@ public extension NSManagedObject { self.setPrimitiveValue(value, forKey: KVCKey) } - /** - Provides a convenience wrapper for setting `setPrimitiveValue(...)` with proper calls to `willChangeValueForKey(...)` and `didChangeValueForKey(...)`. This is useful when implementing mutator methods for transient attributes. - - - parameter value: the value to set the KVC key with - - parameter KVCKey: the KVC key - - parameter didSetPrimitiveValue: the closure called between `willChangeValueForKey(...)` and `didChangeValueForKey(...)` - */ @available(*, deprecated, renamed: "setValue(_:forKvcKey:didSetValue:)") @discardableResult @nonobjc diff --git a/Sources/NSManagedObject+ObjectiveC.swift b/Sources/NSManagedObject+ObjectiveC.swift index d695e65..9caf93e 100644 --- a/Sources/NSManagedObject+ObjectiveC.swift +++ b/Sources/NSManagedObject+ObjectiveC.swift @@ -38,9 +38,9 @@ public extension NSManagedObject { - returns: the primitive value for the KVC key */ @objc - public func cs_accessValueForKVCKey(_ kvcKey: KeyPath) -> Any? { + public func cs_accessValueForKVCKey(_ KVCKey: KeyPath) -> Any? { - return self.getValue(forKvcKey: kvcKey) + return self.getValue(forKvcKey: KVCKey) } /**