Note column names uniqueness constraint on join (#256)

* note uniqueness constraint on join

* clarify raises

Author: MarcoGorelli

spec/API_specification/dataframe_api/dataframe_object.py

@@ -944,6 +944,10 @@ def join(
         """
         Join with other dataframe.
 
+        Other than the joining column name(s), no column name is allowed to appear in
+        both `self` and `other`. Rename columns before calling `join` if necessary
+        using :meth:`rename_columns`.
+
         Parameters
         ----------
         other : DataFrame
@@ -963,4 +967,10 @@ def join(
         Returns
         -------
         DataFrame
+
+        Raises
+        ------
+        ValueError
+            If, apart from `left_on` and `right_on`, there are any column names
+            present in both `self` and `other`.
         """