DOC: Clarify behaviour of pd.merge

[bharatr21]

• Closes DOC:/USAGE: Resulting Index when merging over indices #34412 (also attempts to clarify QST:Different results of pd.merge if using on='key' vs left_on/right_on! #34273)
• tests added / passed (passes scripts/validate_docstrings.py)
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry (Not needed)

[phofl]

We should discuss first if this is the expected behavior. Imo that is pretty weird. The join is exactly the same for both cases, but the result is different. Does not seem consistent.

[jreback]

yeah this actually looks like a bug

[bharatr21]

@jreback @phofl what should the expected behaviour be? Also, some guidance through this part of the code would help (I believe this is responsible for the behaviour):

pandas/pandas/core/reshape/merge.py

Lines 876 to 884 in 433c900

	elif self.right_index and self.how == "left":
	join_index, left_indexer, right_indexer = _left_join_on_index(
	left_ax, right_ax, self.left_join_keys, sort=self.sort
	)
	elif self.left_index and self.how == "right":
	join_index, right_indexer, left_indexer = _left_join_on_index(
	right_ax, left_ax, self.right_join_keys, sort=self.sort
	)

[WillAyd]

I think the index from left should be preserved in both cases no? So the second example is incorrect IMO

[WillAyd]

@Bharat123rox can you try to identify the code paths that cause this inconsistency?

[WillAyd]

Closing for now as I don't think this is something that we should document; probably needs some more discussion on the original issue and a fix to the code instead