Documentation updates for 2.3.0

Docs/Creating-Entities.md

@@ -1,6 +1,6 @@
 # Creating Entities
 
-To create and insert a new instance of an Entity in the current thread's default context, you can use:
+To create and insert a new instance of an Entity in the default context, you can use:
 
 ```objective-c
 Person *myPerson = [Person MR_createEntity];

Docs/Fetching-Entities.md

@@ -1,12 +1,10 @@
 # Fetching Entities
 
-> This document is being revised for MagicalRecord 2.3.0, and may contain information that is out of date. Please refer to the MagicalRecord's headers if anything here doesn't make sense.
-
 #### Basic Finding
 
 Most methods in MagicalRecord return an `NSArray` of results.
 
-As an example, if you have an entity named *Person* related to a *Department* entity (as seen in many examples throughout [Apple's Core Data documentation](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/CoreData/), you can retrieve all of the *Person* entities from your persistent store using the following method:
+As an example, if you have an entity named *Person* related to a *Department* entity (as seen in many of [Apple's Core Data examples](.com/library/mac/documentation/Cocoa/Conceptual/CoreData/Articles/cdBasics.html#//apple_ref/doc/uid/TP40001650-TP1)), you can retrieve all of the *Person* entities from your persistent store using the following method:
 
 ```objective-c
 NSArray *people = [Person MR_findAll];

Docs/Getting-Started.md

@@ -1,5 +1,3 @@
-# Getting Started
-
 To get started, import the `MagicalRecord.h` header file in your project's pch file. This will allow a global include of all the required headers.
 
 If you're using CocoaPods or MagicalRecord.framework, your import should look like:

Docs/Importing-Data.md

@@ -165,3 +165,30 @@ A common scenario is importing JSON data where numeric strings can often be misi
 
 @end
 ```
+
+### Deleting local records on import update
+
+Sometimes you will want to make sure that subsequent import operations not only update but also delete local records that are not included as part of the remote dataset. To do this, fetch all local records not included in this update via their `relatedByAttribute` (`id` in the example below) and remove them immediately before importing the new dataset.
+
+```objective-c
+NSArray *arrayOfPeopleData = /// result from JSON parser
+NSArray *people = [Person MR_importFromArray:arrayOfPeopleData];
+NSArray *idList = [arrayOfPeopleData valueForKey:@"id"];
+NSPredicate *predicate = [NSPredicate predicateWithFormat:@"NOT(id IN %@)", idList];
+[Person MR_deleteAllMatchingPredicate:predicate];
+```
+
+If you also want to make sure that related records are removed during this update, you can use similar logic as above but implement it in the `willImport:` method of `Person`
+
+```objective-c
+
+@implementation Person
+
+-(void)willImport:(id)data {
+    NSArray *idList = [data[@"posts"] valueForKey:@"id"];
+    NSPredicate *predicate = [NSPredicate predicateWithFormat:@"NOT(id IN %@) AND person.id == %@", idList, self.id];
+    [Post MR_deleteAllMatchingPredicate:predicate];
+}
+```
+
+Source: http://stackoverflow.com/a/24252825/401092

Docs/Installing-MagicalRecord.md

@@ -13,26 +13,25 @@ The easiest way to integrate MagicalRecord in your project is to use [CocoaPods]
     ````
 
 2. In your project directory, run `pod update`
-3. You should now be able to add `@import MagicalRecord;` or `#import <MagicalRecord/MagicalRecord.h>` to any of your target's source files and begin using MagicalRecord!
+3. You should now be able to add `#import <MagicalRecord/CoreData+MagicalRecord.h>` to any of your target's source files and begin using MagicalRecord!
 
 ## Using an Xcode subproject
 
 Xcode sub-projects allow your project to use and build MagicalRecord as an implicit dependency.
 
 1. Add MagicalRecord to your project as a Git submodule:
 
-    ````sh
+    ````
     $ cd MyXcodeProjectFolder
     $ git submodule add https://github.com/magicalpanda/MagicalRecord.git Vendor/MagicalRecord
     $ git commit -m "Add MagicalRecord submodule"
     ````
+
 2. Drag `Vendor/MagicalRecord/MagicalRecord.xcproj` into your existing Xcode project
 3. Navigate to your project's settings, then select the target you wish to add MagicalRecord to
 4. Navigate to **Build Phases** and expand the **Link Binary With Libraries** section
-5. Click the **+** and find the version of MagicalRecord appropriate to your target's platform (`libMagicalRecord-iOS.a` for iOS, `libMagicalRecord-OSX.dylib` for OS X)
-6. Navigate to **Build Settings**, then search for **Header Search Paths** and double-click it to edit
-7. Add a new item using **+**: `"$(SRCROOT)/Vendor/MagicalRecord/MagicalRecord"` and ensure that it is set to *recursive*
-8. You should now be able to add `#import "MagicalRecord.h"` to any of your target's source files and begin using MagicalRecord!
+5. Click the **+** and find the version of the MagicalRecord framework appropriate to your target's platform
+6. You should now be able to add `#import <MagicalRecord/MagicalRecord.h>` to any of your target's source files and begin using MagicalRecord!
 
 > **Note** Please be aware that if you've set Xcode's **Link Frameworks Automatically** to **No** then you may need to add the CoreData.framework to your project on iOS, as UIKit does not include Core Data by default. On OS X, Cocoa includes Core Data.
 
@@ -42,7 +41,7 @@ If you don't want to use CocoaPods or use an Xcode subproject, you can add Magic
 
 1. Add MagicalRecord to your project as a Git submodule
 
-    ````sh
+    ````
     $ cd MyXcodeProjectFolder
     $ git submodule add https://github.com/magicalpanda/MagicalRecord.git Vendor/MagicalRecord
     $ git commit -m "Add MagicalRecord submodule"

Docs/Logging.md

@@ -14,10 +14,10 @@ Logging can also be enabled by passing `-DMR_LOGGING_ENABLED=1` to `OTHER_CFLAGS
 Logging can be configured by calling `[MagicalRecord setLoggingLevel:…];` using one of the predefined logging levels:
 
 - **MagicalRecordLogLevelOff**: Don't log anything
-- **MagicalRecordLoggingLevelFatal**: Log all fatal messages
-- **MagicalRecordLoggingLevelError**: Log all errors and fatal messages
-- **MagicalRecordLoggingLevelWarn**: Log warnings, errors and fatal messages
+- **MagicalRecordLoggingLevelError**: Log all errors
+- **MagicalRecordLoggingLevelWarn**: Log warnings and errors
 - **MagicalRecordLoggingLevelInfo**: Log informative, warning and error messages
+- **MagicalRecordLoggingLevelDebug**: Log all debug, informative, warning and error messages
 - **MagicalRecordLoggingLevelVerbose**: Log verbose diagnostic, informative, warning and error messages
 
 The logging level defaults to `MagicalRecordLoggingLevelWarn`.
@@ -31,7 +31,6 @@ Setting the logging level to **MagicalRecordLogLevelOff** completely disables Ma
 If it's available, MagicalRecord will direct its logs to [CocoaLumberjack](https://github.com/CocoaLumberjack/CocoaLumberjack). All you need to do is make sure you've imported CocoaLumberjack before you import MagicalRecord, like so:
 
 ```objective-c
-#import <CocoaLumberjack/DDLog.h>
-#define MR_LOGGING_ENABLED 1
-#import <MagicalRecord/MagicalRecord.h>
+#import <CocoaLumberjack/CocoaLumberjack.h>
+#import <MagicalRecord/CoreData+MagicalRecord.h>
 ```

Docs/Saving-Entities.md

@@ -114,46 +114,35 @@ In MagicalRecord 2.2, the APIs for saving were revised to behave more consistent
 The following methods have been added:
 
 #### NSManagedObjectContext+MagicalSaves
-
-```objective-c
-- (void) MR_saveOnlySelfWithCompletion:(MRSaveCompletionHandler)completion;
-- (void) MR_saveToPersistentStoreWithCompletion:(MRSaveCompletionHandler)completion;
-- (void) MR_saveOnlySelfAndWait;
-- (void) MR_saveToPersistentStoreAndWait;
-- (void) MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompletionHandler)completion;
-```
+- `- (void) MR_saveOnlySelfWithCompletion:(MRSaveCompletionHandler)completion;`
+- `- (void) MR_saveToPersistentStoreWithCompletion:(MRSaveCompletionHandler)completion;`
+- `- (void) MR_saveOnlySelfAndWait;`
+- `- (void) MR_saveToPersistentStoreAndWait;`
+- `- (void) MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompletionHandler)completion;`
 
 #### __MagicalRecord+Actions__
-
-```objective-c
-+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
-+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
-+ (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;
-+ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
-+ (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObjectContext *localContext))block;
-```
+- `+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;`
+- `+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;`
+- `+ (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;`
+- `+ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;`
+- `+ (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObjectContext *localContext))block;`
 
 ### Deprecations
 
 The following methods have been deprecated in favour of newer alternatives, and will be removed in MagicalRecord 3.0:
 
 #### NSManagedObjectContext+MagicalSaves
-
-```objective-c
-- (void) MR_save;
-- (void) MR_saveWithErrorCallback:(void(^)(NSError *error))errorCallback;
-- (void) MR_saveInBackgroundCompletion:(void (^)(void))completion;
-- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback;
-- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;
-- (void) MR_saveNestedContexts;
-- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback;
-- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;
-```
+- `- (void) MR_save;`
+- `- (void) MR_saveWithErrorCallback:(void(^)(NSError *error))errorCallback;`
+- `- (void) MR_saveInBackgroundCompletion:(void (^)(void))completion;`
+- `- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback;`
+- `- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;`
+- `- (void) MR_saveNestedContexts;`
+- `- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback;`
+- `- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion;`
 
 ### MagicalRecord+Actions
-```objective-c
-+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
-+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block;
-+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(void(^)(void))completion;
-+ (void) saveInBackgroundUsingCurrentContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(void (^)(void))completion errorHandler:(void (^)(NSError *error))errorHandler;
-```
+- `+ (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block;`
+- `+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block;`
+- `+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(void(^)(void))completion;`
+- `+ (void) saveInBackgroundUsingCurrentContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(void (^)(void))completion errorHandler:(void (^)(NSError *error))errorHandler;`

Docs/Threads.md

@@ -1,5 +1,3 @@
-
-
 ## Performing Core Data operations on Threads
 
 MagicalRecord also provides some handy methods to set up background context for use with threading. The background saving operations are inspired by the UIView animation block methods, with few minor differences:
@@ -9,37 +7,41 @@ MagicalRecord also provides some handy methods to set up background context for
 
 For example, if we have Person entity, and we need to set the firstName and lastName fields, this is how you would use MagicalRecord to setup a background context for your use:
 
-	Person *person = ...;
-	[MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext){
+```objective-c
+Person *person; // Retrieve person entity
+[MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext) {
 
-		Person *localPerson = [person MR_inContext:localContext];
+	Person *localPerson = [person MR_inContext:localContext];
 
-		localPerson.firstName = @"John";
-		localPerson.lastName = @"Appleseed";
+	localPerson.firstName = @"John";
+	localPerson.lastName = @"Appleseed";
 
-	}];
+}];
+```
 
 In this method, the specified block provides you with the proper context in which to perform your operations, you don't need to worry about setting up the context so that it tells the Default Context that it's done, and should update because changes were performed on another thread.
 
 To perform an action after this save block is completed, you can fill in a completion block:
 
-	Person *person = ...;
-	[MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext){
+```objective-c
+Person *person; // Retrieve person entity
+[MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext){
 
-		Person *localPerson = [person MR_inContext:localContext];
+	Person *localPerson = [person MR_inContext:localContext];
 
-		localPerson.firstName = @"John";
-		localPerson.lastName = @"Appleseed";
+	localPerson.firstName = @"John";
+	localPerson.lastName = @"Appleseed";
 
-	} completion:^(BOOL success, NSError *error) {
+} completion:^(BOOL success, NSError *error) {
 
-		self.everyoneInTheDepartment = [Person findAll];
+	self.everyoneInTheDepartment = [Person findAll];
 
-	}];
+}];
+```
 
 This completion block is called on the main thread (queue), so this is also safe for triggering UI updates.
 
-### Perform blocks syncronously
+### Perform blocks synchronously
 
 If you want to have your code wait until the save block is done, use `[MagicalRecord saveWithBlockAndWait:]`.
 

Docs/Working-with-Managed-Object-Contexts.md

@@ -4,7 +4,7 @@
 
 A variety of simple class methods are provided to help you create new contexts:
 
--  `+ [NSManagedObjectContext MR_newContext]`: Sets the default context as it's parent context. Has a concurrency type of **NSPrivateQueueConcurrencyType**.
+- `+ [NSManagedObjectContext MR_newContext]`: Sets the default context as it's parent context. Has a concurrency type of **NSPrivateQueueConcurrencyType**.
 - `+ [NSManagedObjectContext MR_newMainQueueContext]`: Has a concurrency type of ** NSMainQueueConcurrencyType**.
 - `+ [NSManagedObjectContext MR_newPrivateQueueContext]`: Has a concurrency type of **NSPrivateQueueConcurrencyType**.
 - `+ [NSManagedObjectContext MR_newContextWithParent:…]`: Allows you to specify the parent context that will be set. Has a concurrency type of **NSPrivateQueueConcurrencyType**.