update docstring and add comments for code

pandas/core/internals/managers.py

@@ -1967,11 +1967,14 @@ def items_overlap_with_suffix(left, lsuffix, right, rsuffix):
     if len(to_rename) == 0:
         return left, right
     else:
+        # if column name is string, raise error if suffix is a combination of
+        # empty string and None, or two Nones
         if isinstance(to_rename[0], str):
             if not lsuffix and not rsuffix:
                 raise ValueError('columns overlap but no suffix specified: '
                                  '{rename}'.format(rename=to_rename))
         else:
+            # if not, only suffix with (None, None) will raise error
             if lsuffix is None and rsuffix is None:
                 raise ValueError('columns overlap but no suffix specified: '
                                  '{rename}'.format(rename=to_rename))

pandas/core/reshape/merge.py

@@ -165,7 +165,8 @@ def merge_ordered(left, right, on=None,
         `left` and `right` respectively. Pass a value of `None` instead
         of a string to indicate that the column name from `left` or
         `right` should be left as-is, with no suffix. At least one of the
-        values must not be None.
+        values must not be None. A combination of `''` and `None` is will
+        raise error for columns which type is string
     how : {'left', 'right', 'outer', 'inner'}, default 'outer'
         * left: use only keys from left frame (SQL: left outer join)
         * right: use only keys from right frame (SQL: right outer join)