[ios, macos] clarified documentation for newCamera param of the shouldChangeFromCamera delegate

[samfader]

The newCamera parameter available in the shouldChangeFromCamera: delegate is described as if it becomes a modifiable new camera object - this is not entirely true, and this update to the documentation describes how it works a bit more clearly.

cc @captainbarbosa @fabian-guerra

[fabian-guerra]

Looks good. Just another copy change.

[fabian-guerra]

I think this should be also changed to:

A boolean value indicating wether the map view should stay at oldCamera or transition to newCamera.

[captainbarbosa]

I like @fabian-guerra's suggestion, so consider this approved with his suggested change 👍 thanks!

[natalia-osa]

Why not do it the other way around? Passing newCamera as a reference - so it'd be editable for those who want it, or not for those who don't want it. Or make another delegate to eventually edit it if you want to keep in sync with the old version. Letting the user edit it makes so much sense.

2 examples why it's so useful to edit newCamera:

1. When someone wants to handle restricting map panning to an area in a better way, than just prohibiting any movement when you're close to map border. In reality, when bounds are eg set to US, one would rather prefer not to stop the movement from New York to Pekin, but allow to move it behind California, to the border of US. Returning NO in this method, as you do in the sample (https://docs.mapbox.com/ios/maps/examples/constraining-gestures/), works far from perfect. A simple change to newCamera and overwriting location would be sufficient to do it.

2. If you open Google Maps at zoom 6, centre to UK and scroll right/left you will see the map gets rotated as well. In this scenario, they're doing the rotation to mimic north pole. A simple change of heading in newCamera would be sufficient to do it.

I think it's not the documentation what should be changed but logic. The documentation is pointing the right direction.

[fabian-guerra]

@natalia-osa the update in the documentation is to reflect what is currently happening. The value passed in newCamera is a projection considering the ongoing gesture values (direction, velocity, scale, etc). Due to is a projection we use it with the solely purpose of let you know the camera trajectory.

We also welcome contributions.