Documentation error AnimationOptions for panBy

[cs09g]

Description

panBy allows AnimationOptions as an optinoal parameter. So, it seems like it can be set offset for animation separately from panBy's offset. But if it's set offset on panBy and offset on AnimationOptions, it works with offset on AnimationOptions.

Link to Demonstration

docs:

1. panBy
2. AnimationOptions

fiddle: https://jsfiddle.net/L15dohmx/

// it pans [10, 10], but [100, 100].
// Even, its moving direction is opposite. 
map.panBy([100, 100], { // to right-bottom
  offset: [10, 10] // to left-top
});

Expected Behavior

panBy should not allow offset on AnimationOptions.

Actual Behavior

it overrides offset by AnimationOptions.

[HeyStenson]

The optional options parameter for panBy uses options from AnimationOptions, one of which is offset. However, panBy already has a required offset parameter. According to the OP, if options.offset is specified it overrides the offset param's value in panBy.

The description for the two offsets is different, but I'm having trouble determining what the implications are for a user who chooses to use both offset and options.offset for panBy.

Param/Property	Docs description
offset (panBy)	"x and y coordinates by which to pan the map."
offset (AnimationOptions)	"of the target center relative to real map container center at the end of animation."

I think both of these descriptions could use some clarification, and we should probably add a caveat to the panBy docs about using them together. @mapbox/gl-js could someone assist me with getting a handle on what users need to know here?

[ansis]

I think offset in AnimationOptions doesn't make sense for panBy. The existing behavior isn't ideal but changing it could break some maps.

For panBy, I think documenting that the user shouldn't set offset in AnimationOptions is good.

#4240 also suggests clarifying the AnimationOptions doc.