Improve API and Document usage of mutable fragments for in-memory mutations

[AnthonyMDev]

Regarding the conversation here there have been many requests for mutable models. We may revisit this again in the future, but for the time being, what we've decided is this:

You can currently make a Named Fragment mutable with @apollo_ios_local_cache_mutation and then use that fragment inside of an immutable operation. This should allow you to access that fragment and mutate the fields in it.

We think that this should serve users purposes for now. Rather than making an option for making operations completely mutable, we are considering iterating on that functionality with an improved API and documenting it with usage examples as the correct way to handle this. It allows you to selectively make mutating parts of an operation possible without using the sledgehammer of making everything mutable all the time.

Going forward, we probably want to make a different directive name that is more descriptive of what that does, and maybe make some better API around how you can access and mutate those fields. But for the time being, using this pattern does allow you to workaround this "limitation" (in quotes because it was an intended limitation).

[Mordil]

Just want to raise that this isn't necessarily solved for everyone, as if you don't have named fragments you're still locked out from mutating the object.

I also question the assumption made of confusion related to cache state with mutable objects.

One thing we use extensively in our app code is the raw data we get from queries/mutations, which we modify some state, then at the very end we translate that object into InputObjects, rather than using the InputObjects directly.

While we can workaround this by instead creating a new instance using the initializers - this is going to lead to a ton of boilerplate and code churn, with a tedious upgrade path because the compiler has no straight forward fixits.

Because we don't use named fragments, and adding them would just cause the same amount of work by a different means

[AnthonyMDev]

We are going to implement a better version of this feature. Tracking in #3246