full inline sourcecode documentation

HardcoreData/Saving and Processing/AsynchronousDataTransaction.swift

@@ -31,16 +31,16 @@ import GCDKit
 // MARK: - AsynchronousDataTransaction
 
 /**
-The AsynchronousDataTransaction provides an interface for NSManagedObject creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from DataStack.beginAsynchronous(_:), or from HardcoreData.beginAsynchronous(_:).
+The `AsynchronousDataTransaction` provides an interface for `NSManagedObject` creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from `DataStack.beginAsynchronous(_:)`, or from `HardcoreData.beginAsynchronous(_:)`.
 */
 public final class AsynchronousDataTransaction: BaseDataTransaction {
     
     // MARK: Public
     
     /**
-    Saves the transaction changes asynchronously. This method should not be used after the commit() method was already called once.
+    Saves the transaction changes asynchronously. This method should not be used after the `commit()` method was already called once.
     
-    :param: completion the block executed after the save completes. Success or failure is reported by the SaveResult argument of the block.
+    :param: completion the block executed after the save completes. Success or failure is reported by the `SaveResult` argument of the block.
     */
     public func commit(completion: (result: SaveResult) -> Void) {
         
@@ -59,9 +59,7 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Saves the transaction changes and waits for completion synchronously. This method should not be used after the commit() method was already called once.
-    
-    :returns: a SaveResult value indicating success or failure.
+    Saves the transaction changes and waits for completion synchronously. This method should not be used after the `commit()` method was already called once.
     */
     public func commit() {
         
@@ -73,10 +71,10 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Begins a child transaction synchronously where NSManagedObject creates, updates, and deletes can be made. This method should not be used after he commit() method was already called once.
+    Begins a child transaction synchronously where NSManagedObject creates, updates, and deletes can be made. This method should not be used after the `commit()` method was already called once.
     
-    :param: 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 SaveResult value indicating success or failure, or nil if the transaction was not comitted synchronously
+    :param: 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 `SaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously
     */
     public func beginSynchronous(closure: (transaction: SynchronousDataTransaction) -> Void) -> SaveResult? {
         
@@ -93,10 +91,10 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     // MARK: BaseDataTransaction
     
     /**
-    Creates a new NSManagedObject with the specified entity type. This method should not be used after the commit() method was already called once.
+    Creates a new `NSManagedObject` with the specified entity type. This method should not be used after the `commit()` method was already called once.
     
-    :param: entity the NSManagedObject type to be created
-    :returns: a new NSManagedObject instance of the specified entity type.
+    :param: entity the `NSManagedObject` type to be created
+    :returns: a new `NSManagedObject` instance of the specified entity type.
     */
     public override func create<T: NSManagedObject>(entity: T.Type) -> T {
         
@@ -106,10 +104,10 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Returns an editable proxy of a specified NSManagedObject. This method should not be used after the commit() method was already called once.
+    Returns an editable proxy of a specified `NSManagedObject`. This method should not be used after the `commit()` method was already called once.
     
-    :param: object the NSManagedObject type to be edited
-    :returns: an editable proxy for the specified NSManagedObject.
+    :param: object the `NSManagedObject` type to be edited
+    :returns: an editable proxy for the specified `NSManagedObject`.
     */
     public override func fetch<T: NSManagedObject>(object: T?) -> T? {
         
@@ -119,9 +117,9 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Deletes a specified NSManagedObject. This method should not be used after the commit() method was already called once.
+    Deletes a specified `NSManagedObject`. This method should not be used after the `commit()` method was already called once.
     
-    :param: object the NSManagedObject type to be deleted
+    :param: object the `NSManagedObject` type to be deleted
     */
     public override func delete(object: NSManagedObject?) {
         
@@ -131,7 +129,7 @@ public final class AsynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Rolls back the transaction by resetting the NSManagedObjectContext. After calling this method, all NSManagedObjects fetched within the transaction will become invalid. This method should not be used after the commit() method was already called once.
+    Rolls back the transaction by resetting the `NSManagedObjectContext`. After calling this method, all `NSManagedObjects` fetched within the transaction will become invalid. This method should not be used after the `commit()` method was already called once.
     */
     public override func rollback() {
         

HardcoreData/Saving and Processing/BaseDataTransaction.swift

@@ -31,22 +31,25 @@ import GCDKit
 // MARK: - BaseDataTransaction
 
 /**
-The BaseDataTransaction is an abstract interface for NSManagedObject creates, updates, and deletes. All BaseDataTransaction subclasses manage a private NSManagedObjectContext which are direct children of the NSPersistentStoreCoordinator's root NSManagedObjectContext. This means that all updates are saved first to the persistent store, and then propagated up to the read-only NSManagedObjectContext.
+The `BaseDataTransaction` is an abstract interface for `NSManagedObject` creates, updates, and deletes. All `BaseDataTransaction` subclasses manage a private `NSManagedObjectContext` which are direct children of the `NSPersistentStoreCoordinator`'s root `NSManagedObjectContext`. This means that all updates are saved first to the persistent store, and then propagated up to the read-only `NSManagedObjectContext`.
 */
 public /*abstract*/ class BaseDataTransaction {
     
     // MARK: Object management
     
-    var hasChanges: Bool {
+    /**
+    Indicates if the transaction has pending changes
+    */
+    public var hasChanges: Bool {
         
         return self.context.hasChanges
     }
     
     /**
-    Creates a new NSManagedObject with the specified entity type.
+    Creates a new `NSManagedObject` with the specified entity type.
     
-    :param: entity the NSManagedObject type to be created
-    :returns: a new NSManagedObject instance of the specified entity type.
+    :param: entity the `NSManagedObject` type to be created
+    :returns: a new `NSManagedObject` instance of the specified entity type.
     */
     public func create<T: NSManagedObject>(entity: T.Type) -> T {
         
@@ -56,10 +59,10 @@ public /*abstract*/ class BaseDataTransaction {
     }
     
     /**
-    Returns an editable proxy of a specified NSManagedObject.
+    Returns an editable proxy of a specified `NSManagedObject`.
     
-    :param: object the NSManagedObject type to be edited
-    :returns: an editable proxy for the specified NSManagedObject.
+    :param: object the `NSManagedObject` type to be edited
+    :returns: an editable proxy for the specified `NSManagedObject`.
     */
     public func fetch<T: NSManagedObject>(object: T?) -> T? {
         
@@ -69,9 +72,9 @@ public /*abstract*/ class BaseDataTransaction {
     }
     
     /**
-    Deletes a specified NSManagedObject.
+    Deletes a specified `NSManagedObject`.
     
-    :param: object the NSManagedObject type to be deleted
+    :param: object the `NSManagedObject` type to be deleted
     */
     public func delete(object: NSManagedObject?) {
         
@@ -83,7 +86,7 @@ public /*abstract*/ class BaseDataTransaction {
     // MARK: Saving changes
     
     /**
-    Rolls back the transaction by resetting the NSManagedObjectContext. After calling this method, all NSManagedObjects fetched within the transaction will become invalid.
+    Rolls back the transaction by resetting the `NSManagedObjectContext`. After calling this method, all `NSManagedObjects` fetched within the transaction will become invalid.
     */
     public func rollback() {
         

HardcoreData/Saving and Processing/DataStack+Transaction.swift

@@ -35,9 +35,9 @@ public extension DataStack {
     // MARK: Public
     
     /**
-    Begins a transaction asynchronously where NSManagedObject creates, updates, and deletes can be made.
+    Begins a transaction asynchronously where `NSManagedObject` creates, updates, and deletes can be made.
     
-    :param: 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.
+    :param: 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`.
     */
     public func beginAsynchronous(closure: (transaction: AsynchronousDataTransaction) -> Void) {
         
@@ -50,10 +50,10 @@ public extension DataStack {
     }
     
     /**
-    Begins a transaction synchronously where NSManagedObject creates, updates, and deletes can be made.
+    Begins a transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made.
     
-    :param: 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 SaveResult value indicating success or failure, or nil if the transaction was not comitted synchronously
+    :param: 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 `SaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously
     */
     public func beginSynchronous(closure: (transaction: SynchronousDataTransaction) -> Void) -> SaveResult? {
         
@@ -66,9 +66,9 @@ public extension DataStack {
     }
     
     /**
-    Begins a non-contiguous transaction where NSManagedObject creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
+    Begins a non-contiguous transaction where `NSManagedObject` creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
     
-    :returns: a DetachedDataTransaction instance where creates, updates, and deletes can be made.
+    :returns: a `DetachedDataTransaction` instance where creates, updates, and deletes can be made.
     */
     public func beginDetached() -> DetachedDataTransaction {
         

HardcoreData/Saving and Processing/DetachedDataTransaction.swift

@@ -30,16 +30,16 @@ import GCDKit
 // MARK: - DetachedDataTransaction
 
 /**
-The DetachedDataTransaction provides an interface for non-contiguous NSManagedObject creates, updates, and deletes. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
+The `DetachedDataTransaction` provides an interface for non-contiguous `NSManagedObject` creates, updates, and deletes. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
 */
 public final class DetachedDataTransaction: BaseDataTransaction {
     
     // MARK: Public
     
     /**
-    Saves the transaction changes asynchronously. For a DetachedDataTransaction, multiple commits are allowed, although it is the developer's responsibility to ensure a reasonable leeway to prevent blocking the main thread.
+    Saves the transaction changes asynchronously. For a `DetachedDataTransaction`, multiple commits are allowed, although it is the developer's responsibility to ensure a reasonable leeway to prevent blocking the main thread.
     
-    :param: completion the block executed after the save completes. Success or failure is reported by the SaveResult argument of the block.
+    :param: completion the block executed after the save completes. Success or failure is reported by the `SaveResult` argument of the block.
     */
     public func commit(completion: (result: SaveResult) -> Void) {
         

HardcoreData/Saving and Processing/HardcoreData+Transaction.swift

@@ -33,9 +33,9 @@ public extension HardcoreData {
     // MARK: Public
     
     /**
-    Using the defaultStack, begins a transaction asynchronously where NSManagedObject creates, updates, and deletes can be made.
+    Using the `defaultStack`, begins a transaction asynchronously where `NSManagedObject` creates, updates, and deletes can be made.
     
-    :param: 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.
+    :param: 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`.
     */
     public static func beginAsynchronous(closure: (transaction: AsynchronousDataTransaction) -> Void) {
         
@@ -43,10 +43,10 @@ public extension HardcoreData {
     }
     
     /**
-    Using the defaultStack, begins a transaction asynchronously where NSManagedObject creates, updates, and deletes can be made.
+    Using the `defaultStack`, begins a transaction asynchronously where `NSManagedObject` creates, updates, and deletes can be made.
     
-    :param: 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 SaveResult value indicating success or failure, or nil if the transaction was not comitted synchronously
+    :param: 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 `SaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously
     */
     public static func beginSynchronous(closure: (transaction: SynchronousDataTransaction) -> Void) -> SaveResult? {
         
@@ -54,9 +54,9 @@ public extension HardcoreData {
     }
     
     /**
-    Using the defaultStack, begins a non-contiguous transaction where NSManagedObject creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
+    Using the `defaultStack`, begins a non-contiguous transaction where `NSManagedObject` creates, updates, and deletes can be made. This is useful for making temporary changes, such as partially filled forms. A detached transaction object should typically be only used from the main queue.
     
-    :returns: a DetachedDataTransaction instance where creates, updates, and deletes can be made.
+    :returns: a `DetachedDataTransaction` instance where creates, updates, and deletes can be made.
     */
     public static func beginDetached() -> DetachedDataTransaction {
         

HardcoreData/Saving and Processing/SaveResult.swift

@@ -28,11 +28,52 @@ import Foundation
 
 // MARK: - SaveResult
 
+/**
+The `SaveResult` indicates the result of a `commit(...)` for a transaction.
+The `SaveResult` can be treated as a boolean:
+
+    HardcoreData.beginAsynchronous { transaction in
+        // ...
+        let result = transaction.commit()
+        if result {
+            // succeeded
+        }
+        else {
+            // failed
+        }
+    }
+
+or as an `enum`, where the resulting associated object can also be inspected:
+
+    HardcoreData.beginAsynchronous { transaction in
+        // ...
+        let result = transaction.commit()
+        switch result {
+        case .Success(let hasChanges):
+            // hasChanges indicates if there were changes or not
+        case .Failure(let error):
+            // error is the NSError instance for the failure
+        }
+    }
+```
+*/
 public enum SaveResult {
     
+    // MARK: Public
+    
+    /**
+    `SaveResult.Success` indicates that the `commit()` for the transaction succeeded, either because the save succeeded or because there were no changes to save. The associated value `hasChanges` indicates if there were saved changes or not.
+    */
     case Success(hasChanges: Bool)
+    
+    /**
+    `SaveResult.Failure` indicates that the `commit()` for the transaction failed. The associated object for this value is the related `NSError` instance.
+    */
     case Failure(NSError)
     
+    
+    // MARK: Internal
+    
     internal init(hasChanges: Bool) {
         
         self = .Success(hasChanges: hasChanges)

HardcoreData/Saving and Processing/SynchronousDataTransaction.swift

@@ -31,16 +31,14 @@ import GCDKit
 // MARK: - SynchronousDataTransaction
 
 /**
-The SynchronousDataTransaction provides an interface for NSManagedObject creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from DataStack.beginSynchronous(_:), or from HardcoreData.beginSynchronous(_:).
+The `SynchronousDataTransaction` provides an interface for `NSManagedObject` creates, updates, and deletes. A transaction object should typically be only used from within a transaction block initiated from `DataStack.beginSynchronous(_:)`, or from `HardcoreData.beginSynchronous(_:)`.
 */
 public final class SynchronousDataTransaction: BaseDataTransaction {
     
     // MARK: Public
     
     /**
-    Saves the transaction changes and waits for completion synchronously. This method should not be used after the commit() method was already called once.
-    
-    :returns: a SaveResult value indicating success or failure.
+    Saves the transaction changes and waits for completion synchronously. This method should not be used after the `commit()` method was already called once.
     */
     public func commit() {
         
@@ -52,10 +50,10 @@ public final class SynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Begins a child transaction synchronously where NSManagedObject creates, updates, and deletes can be made. This method should not be used after the commit() method was already called once.
+    Begins a child transaction synchronously where `NSManagedObject` creates, updates, and deletes can be made. This method should not be used after the `commit()` method was already called once.
     
-    :param: 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 SaveResult value indicating success or failure, or nil if the transaction was not comitted synchronously
+    :param: 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 `SaveResult` value indicating success or failure, or `nil` if the transaction was not comitted synchronously
     */
     public func beginSynchronous(closure: (transaction: SynchronousDataTransaction) -> Void) -> SaveResult? {
         
@@ -72,10 +70,10 @@ public final class SynchronousDataTransaction: BaseDataTransaction {
     // MARK: BaseDataTransaction
     
     /**
-    Creates a new NSManagedObject with the specified entity type. This method should not be used after the commit() method was already called once.
+    Creates a new `NSManagedObject` with the specified entity type. This method should not be used after the `commit()` method was already called once.
     
-    :param: entity the NSManagedObject type to be created
-    :returns: a new NSManagedObject instance of the specified entity type.
+    :param: entity the `NSManagedObject` type to be created
+    :returns: a new `NSManagedObject` instance of the specified entity type.
     */
     public override func create<T: NSManagedObject>(entity: T.Type) -> T {
         
@@ -85,10 +83,10 @@ public final class SynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Returns an editable proxy of a specified NSManagedObject. This method should not be used after the commit() method was already called once.
+    Returns an editable proxy of a specified `NSManagedObject`. This method should not be used after the `commit()` method was already called once.
     
-    :param: object the NSManagedObject type to be edited
-    :returns: an editable proxy for the specified NSManagedObject.
+    :param: object the `NSManagedObject` type to be edited
+    :returns: an editable proxy for the specified `NSManagedObject`.
     */
     public override func fetch<T: NSManagedObject>(object: T?) -> T? {
         
@@ -98,9 +96,9 @@ public final class SynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Deletes a specified NSManagedObject. This method should not be used after the commit() method was already called once.
+    Deletes a specified `NSManagedObject`. This method should not be used after the `commit()` method was already called once.
     
-    :param: object the NSManagedObject type to be deleted
+    :param: object the `NSManagedObject` type to be deleted
     */
     public override func delete(object: NSManagedObject?) {
         
@@ -110,7 +108,7 @@ public final class SynchronousDataTransaction: BaseDataTransaction {
     }
     
     /**
-    Rolls back the transaction by resetting the NSManagedObjectContext. After calling this method, all NSManagedObjects fetched within the transaction will become invalid. This method should not be used after the commit() method was already called once.
+    Rolls back the transaction by resetting the `NSManagedObjectContext`. After calling this method, all `NSManagedObjects` fetched within the transaction will become invalid. This method should not be used after the `commit()` method was already called once.
     */
     public override func rollback() {