WIP: readme

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;

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

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

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? {

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

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

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? {

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

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) {
         

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: ()) {
         

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

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 {

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] {
         

Sources/CoreStoreBridge.h

@@ -156,7 +156,7 @@ CSFrom *_Nonnull CSFromClass(Class _Nonnull entityClass, NSArray<id> *_Nonnull c
  @abstract
  Initializes a <tt>CSGroupBy</tt> 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 <tt>CSGroupBy</tt> 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 <tt>NSSortDescriptor</tt>s
  
  @result
@@ -473,9 +473,6 @@ CSSelect *_Nonnull CSSelectData(CSSelectTerm *_Nonnull selectTerm) CORESTORE_RET
     // ...
  @endcode
  
- @param selectTerm
- the <tt>CSSelectTerm</tt> specifying the attribute/aggregate value to query
- 
  @result
  a <tt>CSSelect</tt> clause for querying an <tt>NSManagedObjectID</tt> value
  */
@@ -538,10 +535,7 @@ CSWhere *_Nonnull CSWhereValue(BOOL value) CORESTORE_RETURNS_RETAINED;
  @endcode
  
  @param format
- the format string for the predicate
+ the format string for the predicate, followed by an optional comma-separated argument list
- 
- @param argumentArray
- the arguments for <tt>format</tt>
  
  @result
  a <tt>CSWhere</tt> clause with a predicate using the specified string format and arguments

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] {
         

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<NSManagedObject> {
@@ -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<NSManagedObject> {

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<T>(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<T>(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<T>(_ 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

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)
     }
     
     /**