Open Radar

 
Area:
Core Data

Summary:

I find it difficult to interpret and differentiate the documentation descriptions of NSMergePolicy.mergeByPropertyObjectTrump and NSMergePolicy.mergeByPropertyStoreTrump in order to determine which I should use.

Current documentation:

`class var mergeByPropertyObjectTrump: NSMergePolicy`

> A policy that merges conflicts between the persistent store's version of the object and the current in-memory version by individual property, with the external changes trumping in-memory changes.

`class var mergeByPropertyStoreTrump: NSMergePolicy`

> A policy that merges conflicts between the persistent store's version of the object and the current in-memory version by individual property, with the in-memory changes trumping external changes.

The phrase "in-memory" seems to be used to refer to both the context (as opposed to the persistent store) in the first half, and then to the persistent store (as opposed to the context) in the second half. The second half also introduces the term "external". I'm assuming this is referring to the context which would be external from the perspective of the store. It's unclear though, when mergePolicy is a property on NSManagedObjectContext, and "external" could also refer to a system external to all of the Core Data components such as when merging data from an API.

I would suggest using the same terms throughout the descriptions. It's perhaps too late for this but it would be even better to change the name of one of the policies slightly, if I'm understanding how it works correctly. It's very likely I'm missing some subtlety that would make this change inappropriate though. :)

Easier suggestion:

`class var mergeByPropertyObjectTrump: NSMergePolicy`

> A policy that merges conflicts between the persistent store's version of the object and the current context's version by individual property, with the context's changes trumping the store's changes.

`class var mergeByPropertyStoreTrump: NSMergePolicy`

> A policy that merges conflicts between the persistent store's version of the object and the current context's version by individual property, with the store's changes trumping the context's changes.

Ideal suggestion:

The above description changes as well as aliasing `mergeByPropertyObjectTrump` to `mergeByPropertyContextTrump `

Steps to Reproduce:

Read the documentation.

Expected Results:

That the descriptions use canonical terms for the involved components and the difference between these two similar policies is easy to understand.

Actual Results:

I found it difficult to rely on the documentation's descriptions and 3rd party resources found online were required in order to confirm how the policies work.

Version/Build:

iOS 11.2 SDK

Configuration:

Version 9.2 (9C40b)