Update fetching document

Author: tonyarnold

Docs/Fetching.md

@@ -2,76 +2,92 @@
 
 #### Basic Finding
 
-Most methods in MagicalRecord return an NSArray of results. So, if you have an Entity called Person, related to a Department (as seen in various Apple Core Data documentation), to get all the Person entities from your Persistent Store:
+Most methods in MagicalRecord return an `NSArray` of results.
 
-	//In order for this to work you need to add "#define MR_SHORTHAND" to your PCH file
-	NSArray *people = [Person findAll];
+Say you have an Entity called "Person", related to a Department (as seen in various Apple Core Data documentation). To get all of the Person entities from your Persistent Store, use the following method:
 
-	// Otherwise you can use the longer, namespaced version
-	NSArray *people = [Person MR_findAll];
+```objective-c
+NSArray *people = [Person MR_findAll];
+```
+
+Or, to return the results sorted by a property:
 
-Or, to have the results sorted by a property:
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName" ascending:YES];
+```
 
-	NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName" ascending:YES];
+Or, to return the results sorted by multiple properties:
 
-Or, to have the results sorted by multiple properties:
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName" ascending:YES];
+```
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName" ascending:YES];
+Or, to return the results sorted by multiple properties with different attributes (these will default to whatever you set them to):
 
-Or, to have the results sorted by multiple properties with difference attributes - will default to whatever you set it to:
+```objective-c
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName" ascending:YES];
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName" ascending:YES];
+// OR
 
-        NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES" ascending:NO];
+NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES" ascending:NO];
+```
 
-If you have a unique way of retrieving a single object from your data store, you can get that object directly:
+If you have a unique way of retrieving a single object from your data store (such as via an identifier), you can use the following method:
 
-	Person *person = [Person MR_findFirstByAttribute:@"FirstName" withValue:@"Forrest"];
+```objective-c
+Person *person = [Person MR_findFirstByAttribute:@"FirstName" withValue:@"Forrest"];
+```
 
 #### Advanced Finding
 
 If you want to be more specific with your search, you can send in a predicate:
 
-	NSArray *departments = [NSArray arrayWithObjects:dept1, dept2, ..., nil];
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
-
-	NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", @[dept1, dept2]];
+NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```
 
 #### Returning an NSFetchRequest
 
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
-
-	NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];
+```
 
 For each of these single line calls, the full stack of NSFetchRequest, NSSortDescriptors and a simple default error handling scheme (ie. logging to the console) is created.
 
 #### Customizing the Request
 
-	NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
+```objective-c
+NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];
 
-	NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
-	[peopleRequest setReturnsDistinctResults:NO];
-	[peopleRequest setReturnPropertiesNamed:[NSArray arrayWithObjects:@"FirstName", @"LastName", nil]];
-	...
+NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];
+[peopleRequest setReturnsDistinctResults:NO];
+[peopleRequest setReturnPropertiesNamed:@[@"FirstName", @"LastName"]];
 
-	NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
+NSArray *people = [Person MR_executeFetchRequest:peopleRequest];
+```
 
 #### Find the number of entities
 
-You can also perform a count of entities in your Store, that will be performed on the Store
+You can also perform a count of all entities of a specific type in your Persistent Store:
 
-	NSNumber *count = [Person MR_numberOfEntities];
+```objective-c
+NSNumber *count = [Person MR_numberOfEntities];
+```
 
 Or, if you're looking for a count of entities based on a predicate or some filter:
 
-	NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
-	
-There are also counterpart methods which return NSUInteger rather than NSNumbers:
+```objective-c
+NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];
+```
+
+There are also complementary methods which return `NSUInteger` rather than `NSNumber` instances:
 
-* countOfEntities
-* countOfEntitiesWithContext:(NSManagedObjectContext *)
-* countOfEntitiesWithPredicate:(NSPredicate *)
-* countOfEntitiesWithPredicate:(NSPredicate *) inContext:(NSManagedObjectContext *)
+* `MR_countOfEntities`
+* `MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context`
+* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicate`
+* `MR_countOfEntitiesWithPredicate:(NSPredicate *)predicatecontext inContext:(NSManagedObjectContext *)`
 
 #### Aggregate Operations
 
@@ -80,56 +96,55 @@ NSInteger totalFat = [[CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribut
 NSInteger fattest  = [[CTFoodDiaryEntry MR_aggregateOperation:@"max:" onAttribute:@"fatCalories" withPredicate:predicate] integerValue];
 NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"fatCalories" withPredicate:predicate groupBy:@"month"];
 ```
-    
+
 #### Finding from a different context
 
 All find, fetch, and request methods have an inContext: method parameter
 
-	NSManagedObjectContext *someOtherContext = ...;
-
-	NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
-
-	...
-
-	Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];
-
-	...
+```objective-c
+NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];
 
-	NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
+Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];
 
+NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];
+```
 
 ## Creating new Entities
 
 When you need to create a new instance of an Entity, use:
 
-	Person *myNewPersonInstance = [Person MR_createEntity];
-
-or, to specify a context:
-
-	NSManagedObjectContext *otherContext = ...;
+```objective-c
+Person *myPerson = [Person MR_createEntity];
+```
 
-	Person *myPerson = [Person MR_createInContext:otherContext];
+or, to specify which context the entity is inserted into:
 
+```objective-c
+Person *myPerson = [Person MR_createInContext:otherContext];
+```
 
 ## Deleting Entities
 
 To delete a single entity:
 
-	Person *p = ...;
-	[p  MR_deleteEntity];
-
-or, to specify a context:
+```objective-c
+[myPerson MR_deleteEntity];
+```
 
-	NSManagedObjectContext *otherContext = ...;
-	Person *deleteMe = ...;
+or, to delete the entity from a specific context:
 
-	[deleteMe MR_deleteInContext:otherContext];
+```objective-c
+[myPerson MR_deleteInContext:otherContext];
+```
 
 There is no delete *All Entities* or *truncate* operation in core data, so one is provided for you with Active Record for Core Data:
 
-	[Person MR_truncateAll];
+```objective-c
+[Person MR_truncateAll];
+```
 
-or, with a specific context:
+or, to truncate all entities in a specific context:
 
-	NSManagedObjectContext *otherContext = ...;
-	[Person MR_truncateAllInContext:otherContext];
+```objective-c
+[Person MR_truncateAllInContext:otherContext];
+```