DOC/ERR: better error message on no common merge keys

- Let MergeError emit values keyword arguments.
- Add DataFrame.join on 'See also' section of
  pandas.merge.
- Add an item in whatsnew

Author: swyoon

doc/source/whatsnew/v0.23.0.txt

@@ -538,6 +538,7 @@ Reshaping
 - Bug in :func:`DataFrame.merge` in which merging using ``Index`` objects as vectors raised an Exception (:issue:`19038`)
 - Bug in :func:`DataFrame.stack`, :func:`DataFrame.unstack`, :func:`Series.unstack` which were not returning subclasses (:issue:`15563`)
 - Bug in timezone comparisons, manifesting as a conversion of the index to UTC in ``.concat()`` (:issue:`18523`)
+- Improved error message for :func:`DataFrame.merge` when there is no common merge key (:issue:`19427`)
 -
 
 

pandas/core/frame.py

@@ -233,7 +233,7 @@
 --------
 merge_ordered
 merge_asof
-
+DataFrame.join
 """
 
 # -----------------------------------------------------------------------

pandas/core/reshape/merge.py

@@ -1028,7 +1028,14 @@ def _validate_specification(self):
                 common_cols = self.left.columns.intersection(
                     self.right.columns)
                 if len(common_cols) == 0:
-                    raise MergeError('No common columns to perform merge on')
+                    raise MergeError('No common columns to perform merge on. '
+                                     'Merge options: right_on={ron}, '
+                                     'left_on={lon}, right_index={ridx}, '
+                                     'left_index={lidx}'
+                                     .format(ron=self.right_on,
+                                             lon=self.left_on,
+                                             ridx=self.right_index,
+                                             lidx=self.left_index))
                 if not common_cols.is_unique:
                     raise MergeError("Data columns not unique: {common!r}"
                                      .format(common=common_cols))