Permalink
Browse files

Update documentation and ensure that deprecated methods are defined a…

…nd implemented in class extensions
  • Loading branch information...
1 parent 77e3fc0 commit 9f7f07397665a6f1f8396be2984e67bfff4ebe62 @tonyarnold tonyarnold committed May 4, 2014
@@ -64,12 +64,14 @@
/**
Initializes a context of type `NSMainQueueConcurrencyType`.
+
@return A context initialized using the `NSPrivateQueueConcurrencyType` concurrency type.
*/
+ (NSManagedObjectContext *) MR_newMainQueueContext NS_RETURNS_RETAINED;
/**
Initializes a context of type `NSPrivateQueueConcurrencyType`.
+
@return A context initialized using the `NSPrivateQueueConcurrencyType` concurrency type.
*/
+ (NSManagedObjectContext *) MR_newPrivateQueueContext NS_RETURNS_RETAINED;
@@ -78,6 +80,7 @@
/**
Sets a working name for the context, which will be used in debug logs.
+
@param workingName Name for the context
*/
- (void) MR_setWorkingName:(NSString *)workingName;
@@ -10,87 +10,82 @@
#import "MagicalRecordDeprecated.h"
typedef NS_OPTIONS(NSUInteger, MRSaveContextOptions) {
- MRSaveWithoutOptions = 0, ///< No options — used for cleanliness only
- MRSaveParentContexts = 1 << 1, ///< When saving, continue saving parent contexts until the changes are present in the persistent store
- MRSaveSynchronously = 1 << 2, ///< Perform saves synchronously, blocking execution on the current thread until the save is complete
- MRSaveAllSynchronouslyExceptRoot = 1 << 3 ///< Perform saves synchronously, blocking execution on the current thread until the save is complete; however, save root context asynchronously
+ /** No options — used for cleanliness only */
+ MRSaveWithoutOptions = 0,
+
+ /** When saving, continue saving parent contexts until the changes are present in the persistent store */
+ MRSaveParentContexts = 1 << 1,
+
+ /** Perform saves synchronously, blocking execution on the current thread until the save is complete */
+ MRSaveSynchronously = 1 << 2,
+
+ /** Perform saves synchronously, blocking execution on the current thread until the save is complete; however, save root context asynchronously */
+ MRSaveAllSynchronouslyExceptRoot = 1 << 3
};
typedef void (^MRSaveCompletionHandler)(BOOL success, NSError *error);
@interface NSManagedObjectContext (MagicalSaves)
-/// \brief Asynchronously save changes in the current context and it's parent
-/// \param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
-/// \discussion Executes a save on the current context's dispatch queue asynchronously. This method only saves the current context, and the parent of the current context if one is set. The completion block will always be called on the main queue.
+/**
+ Asynchronously save changes in the current context and it's parent.
+ Executes a save on the current context's dispatch queue asynchronously. This method only saves the current context, and the parent of the current context if one is set. The completion block will always be called on the main queue.
+
+ @param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
+
+ @since Available in v2.1.0 and later.
+*/
- (void) MR_saveOnlySelfWithCompletion:(MRSaveCompletionHandler)completion;
-/// \brief Asynchronously save changes in the current context all the way back to the persistent store
-/// \param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
-/// \discussion Executes asynchronous saves on the current context, and any ancestors, until the changes have been persisted to the assigned persistent store. The completion block will always be called on the main queue.
+/**
+ Asynchronously save changes in the current context all the way back to the persistent store.
+ Executes asynchronous saves on the current context, and any ancestors, until the changes have been persisted to the assigned persistent store. The completion block will always be called on the main queue.
+
+ @param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
+
+ @since Available in v2.1.0 and later.
+ */
- (void) MR_saveToPersistentStoreWithCompletion:(MRSaveCompletionHandler)completion;
-/// \brief Synchronously save changes in the current context and it's parent
-/// \discussion Executes a save on the current context's dispatch queue. This method only saves the current context, and the parent of the current context if one is set. The method will not return until the save is complete.
+/**
+ Synchronously save changes in the current context and it's parent.
+ Executes a save on the current context's dispatch queue. This method only saves the current context, and the parent of the current context if one is set. The method will not return until the save is complete.
+
+ @since Available in v2.1.0 and later.
+ */
- (void) MR_saveOnlySelfAndWait;
-/// \brief Synchronously save changes in the current context all the way back to the persistent store
-/// \discussion Executes saves on the current context, and any ancestors, until the changes have been persisted to the assigned persistent store. The method will not return until the save is complete.
+/**
+ Synchronously save changes in the current context all the way back to the persistent store.
+ Executes saves on the current context, and any ancestors, until the changes have been persisted to the assigned persistent store. The method will not return until the save is complete.
+
+ @since Available in v2.1.0 and later.
+ */
- (void) MR_saveToPersistentStoreAndWait;
-/// \brief Save the current context with options
-/// \param mask bitmasked options for the save process
-/// \param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
-/// \discussion All other save methods are conveniences to this method.
-- (void) MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompletionHandler)completion;
+/**
+ Save the current context with options.
+ All other save methods are conveniences to this method.
+ @param mask Bitmasked options for the save process.
+ @param completion Completion block that is called after the save has completed. The block is passed a success state as a `BOOL` and an `NSError` instance if an error occurs. Always called on the main queue.
-/* DEPRECATION NOTICE:
- * The following methods are deprecated, but remain in place for backwards compatibility until the next major version (3.x)
+ @since Available in v2.1.0 and later.
*/
+- (void) MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompletionHandler)completion;
-/// \brief Synchronously save changes in the current context all the way back to the persistent store
-/// \discussion Replaced by \MR_saveToPersistentStoreAndWait
-/// \deprecated
-- (void) MR_save MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE("Please use MR_saveToPersistentStoreAndWait instead.");
+@end
-/// \brief Synchronously save changes in the current context all the way back to the persistent store
-/// \param errorCallback Block that is called if an error is encountered while saving. Always called on the main thread.
-/// \deprecated
-- (void) MR_saveWithErrorCallback:(void(^)(NSError *error))errorCallback MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
+#pragma mark - Deprecated Methods — DO NOT USE
+@interface NSManagedObjectContext (MagicalSavesDeprecated)
-/// \brief Asynchronously save changes in the current context and it's parent
-/// \param completion Completion block that is called after the save has completed. Always called on the main queue.
-/// \deprecated
+- (void) MR_save MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE("Please use MR_saveToPersistentStoreAndWait instead.");
+- (void) MR_saveWithErrorCallback:(void(^)(NSError *error))errorCallback MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
- (void) MR_saveInBackgroundCompletion:(void (^)(void))completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-
-/// \brief Asynchronously save changes in the current context and it's parent
-/// \param errorCallback Block that is called if an error is encountered while saving. Always called on the main thread.
-/// \deprecated
- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-
-/// \brief Asynchronously save changes in the current context and it's parent
-/// \param errorCallback Block that is called if an error is encountered while saving. Always called on the main thread.
-/// \param completion Completion block that is called after the save has completed. Always called on the main queue.
-/// \deprecated
- (void) MR_saveInBackgroundErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-
-/// \brief Asynchronously save changes in the current context all the way back to the persistent store
-/// \discussion Replaced by \MR_saveToPersistentStoreWithCompletion:
-/// \deprecated
- (void) MR_saveNestedContexts MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE("Please use MR_saveToPersistentStoreWithCompletion: instead.");
-
-/// \brief Asynchronously save changes in the current context all the way back to the persistent store
-/// \param errorCallback Block that is called if an error is encountered while saving. Always called on the main thread.
-/// \discussion Replaced by \MR_saveToPersistentStoreWithCompletion:
-/// \deprecated
- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE("Please use MR_saveToPersistentStoreWithCompletion: instead.");
-
-/// \brief Asynchronously save changes in the current context all the way back to the persistent store
-/// \param errorCallback Block that is called if an error is encountered while saving. Always called on the main thread.
-/// \param completion Completion block that is called after the save has completed. Always called on the main queue.
-/// \discussion Replaced by \MR_saveToPersistentStoreWithCompletion:
-/// \deprecated
- (void) MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallback completion:(void (^)(void))completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE("Please use MR_saveToPersistentStoreWithCompletion: instead.");
@end
@@ -108,11 +108,10 @@ - (void)MR_saveWithOptions:(MRSaveContextOptions)mask completion:(MRSaveCompleti
}
}
-#pragma mark - Deprecated methods
-// These methods will be removed in MagicalRecord 3.0
+@end
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-implementations"
+#pragma mark - Deprecated Methods — DO NOT USE
+@implementation NSManagedObjectContext (MagicalSavesDeprecated)
- (void)MR_save;
{
@@ -198,6 +197,4 @@ - (void)MR_saveNestedContextsErrorHandler:(void (^)(NSError *error))errorCallbac
}];
}
-#pragma clang diagnostic pop // ignored "-Wdeprecated-implementations"
-
@end
@@ -20,25 +20,14 @@
*/
+ (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;
-/*
- If you want to reuse the context on the current thread, use these methods.
- */
-+ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-+ (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObjectContext *localContext))block MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-
+@end
-/* DEPRECATION NOTICE:
- * The following methods are deprecated, but remain in place for backwards compatibility until the next major version (3.x)
- */
+@interface MagicalRecord (ActionsDeprecated)
-/* For all background saving operations. These calls will be sent to a different thread/queue.
- */
++ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
++ (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObjectContext *localContext))block MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block completion:(void(^)(void))completion MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
-
-/*
- If you want to reuse the context on the current thread, use this method.
- */
+ (void) saveInBackgroundUsingCurrentContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(void (^)(void))completion errorHandler:(void (^)(NSError *error))errorHandler MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0;
@end
@@ -34,37 +34,41 @@ + (void) saveWithBlock:(void(^)(NSManagedObjectContext *localContext))block comp
}];
}
-+ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
+#pragma mark - Synchronous saving
+
++ (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;
{
- NSManagedObjectContext *localContext = [NSManagedObjectContext MR_contextForCurrentThread];
+ NSManagedObjectContext *savingContext = [NSManagedObjectContext MR_rootSavingContext];
+ NSManagedObjectContext *localContext = [NSManagedObjectContext MR_contextWithParent:savingContext];
[localContext MR_setWorkingName:NSStringFromSelector(_cmd)];
- [localContext performBlock:^{
+ [localContext performBlockAndWait:^{
if (block) {
block(localContext);
}
- [localContext MR_saveWithOptions:MRSaveParentContexts completion:completion];
+ [localContext MR_saveWithOptions:MRSaveParentContexts|MRSaveSynchronously completion:nil];
}];
}
+@end
-#pragma mark - Synchronous saving
+#pragma mark - Deprecated Methods — DO NOT USE
+@implementation MagicalRecord (ActionsDeprecated)
-+ (void) saveWithBlockAndWait:(void(^)(NSManagedObjectContext *localContext))block;
++ (void) saveUsingCurrentThreadContextWithBlock:(void (^)(NSManagedObjectContext *localContext))block completion:(MRSaveCompletionHandler)completion;
{
- NSManagedObjectContext *savingContext = [NSManagedObjectContext MR_rootSavingContext];
- NSManagedObjectContext *localContext = [NSManagedObjectContext MR_contextWithParent:savingContext];
+ NSManagedObjectContext *localContext = [NSManagedObjectContext MR_contextForCurrentThread];
[localContext MR_setWorkingName:NSStringFromSelector(_cmd)];
- [localContext performBlockAndWait:^{
+ [localContext performBlock:^{
if (block) {
block(localContext);
}
- [localContext MR_saveWithOptions:MRSaveParentContexts|MRSaveSynchronously completion:nil];
+ [localContext MR_saveWithOptions:MRSaveParentContexts completion:completion];
}];
}
@@ -83,12 +87,6 @@ + (void) saveUsingCurrentThreadContextWithBlockAndWait:(void (^)(NSManagedObject
}];
}
-
-#pragma mark - Deprecated methods
-
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-implementations"
-
+ (void) saveInBackgroundWithBlock:(void(^)(NSManagedObjectContext *localContext))block
{
[[self class] saveWithBlock:block completion:nil];
@@ -142,6 +140,4 @@ + (void) saveInBackgroundUsingCurrentContextWithBlock:(void (^)(NSManagedObjectC
}];
}
-#pragma clang diagnostic pop // ignored "-Wdeprecated-implementations"
-
@end
@@ -3,5 +3,5 @@
// Copyright (c) 2014 Magical Panda Software LLC. All rights reserved.
//
-#define MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0 __attribute__((deprecated("This method will be removed in MagicalRecord 3.0")))
+#define MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0 __attribute__((deprecated("This method will be removed in MagicalRecord 3.0.")))
#define MR_DEPRECATED_WILL_BE_REMOVED_IN_3_0_USE(MSG) __attribute__((deprecated("This method will be removed in MagicalRecord 3.0. " MSG)))

0 comments on commit 9f7f073

Please sign in to comment.