doc: Describe potential footgun in MapArray::keys and values

[neilconway]

Which issue does this PR close?

• N/A

Rationale for this change

The behavior of the keys and values methods of a MapArray can be a bit surprising. This PR documents that behavior; consistent with the documentation for ListArray::values, which behaves similarly.

What changes are included in this PR?

• Doc additions only

Are these changes tested?

Existing tests pass.

Are there any user-facing changes?

No.

[neilconway]

Noticed this in apache/datafusion#25543

[Rich-T-kid]

makes sense to me. I left a suggestion but its fine as it is.

In my opinion, the extra info on how to get the specific slice range your looking for would be better placed as a doc comment on [Self::value_offsets].

[Rich-T-kid]

Suggested change

	/// Returns a reference to the keys of this map
	///
	/// Note: The map array may not refer to all keys in the returned array.
	/// For example, after slicing via [`Self::slice`], the returned array may
	/// contain keys both before and after the slice. Use [`Self::value_offsets`]
	/// to determine the range of keys for each map. These offsets index into
	/// the returned array and may not start at zero.
	/// Returns a reference to all the keys of this map
	/// this includes keys that may have been [`Self::slice`]'ed off