Fixed pandas.DataFrame().join() function.
Added on_right and on_left keywords.
Now a right.join(left,on=key) works as expected.

Old behavior is archived by right.join(left,left_on=key) 

Tested multi-index funtionallity.

```
import pandas as pd
from copy import copy
print pd.__file__
left = pd.DataFrame({'A': ['A0', 'A1', 'A2', 'A3','A4'],
                   'key': ['K0', 'K1', 'K3', 'K4','K5']})
right = pd.DataFrame({'C': ['C0', 'C1', 'C2', 'C3'],
                   'key': ['K0', 'K2', 'K1', 'K3']},
                    index=[4,5,6,7])

print left.join(right,on='key',how="outer",rsuffix="_r")
```

Old result:

```
     A key    C key_r
0   A0  K0  NaN   NaN
1   A1  K1  NaN   NaN
2   A2  K3  NaN   NaN
3   A3  K4  NaN   NaN
4   A4  K5  NaN   NaN
4  NaN   4   C0    K0
4  NaN   5   C1    K2
4  NaN   6   C2    K1
4  NaN   7   C3    K3
```

New result:

```
     A key    C
0   A0  K0   C0
1   A1  K1   C2
2   A2  K3   C3
3   A3  K4  NaN
4   A4  K5  NaN
5  NaN  K2   C1
```

I'm not sure the old behavior was a bug.

From the docs:

> join takes an optional on argument which may be a column or multiple column names, which specifies that the passed DataFrame is to be aligned on that column in the DataFrame

so I think `left.join(right, on='key')` is equivalent to `pd.merge(left, right, left_on='key', right_index=True)`, not `pd.merge(left, right, on='key')`.
 The example that you showed is not equivalent.

```
left.join(right, on='key',rsuffix="_r")
    A key    C key_r
0  A0  K0  NaN   NaN
1  A1  K1  NaN   NaN
2  A2  K3  NaN   NaN
3  A3  K4  NaN   NaN
4  A4  K5  NaN   NaN
```

and 

```
pd.merge(left, right, left_on='key', right_index=True)

Empty DataFrame
Columns: [key, A, key_x, C, key_y]
Index: []
```
 ``` python
n [5]: left.join(right, on='key', rsuffix='_y', lsuffix='_x', how='outer')
Out[5]:
  key    A key_x    C key_y
0  K0   A0    K0  NaN   NaN
1  K1   A1    K1  NaN   NaN
2  K3   A2    K3  NaN   NaN
3  K4   A3    K4  NaN   NaN
4  K5   A4    K5  NaN   NaN
4   4  NaN   NaN   C0    K0
4   5  NaN   NaN   C1    K2
4   6  NaN   NaN   C2    K1
4   7  NaN   NaN   C3    K3

In [6]: pd.merge(left, right, left_on='key', right_index=True, how='outer')
Out[6]:
  key    A key_x    C key_y
0  K0   A0    K0  NaN   NaN
1  K1   A1    K1  NaN   NaN
2  K3   A2    K3  NaN   NaN
3  K4   A3    K4  NaN   NaN
4  K5   A4    K5  NaN   NaN
4   4  NaN   NaN   C0    K0
4   5  NaN   NaN   C1    K2
4   6  NaN   NaN   C2    K1
4   7  NaN   NaN   C3    K3
```

Just to step through what's going on here there's an `align` done _before_ the merge/join (roughly `left.align(right.set_index('key'))`). Then that goes into the merge.
 Ok, now it has the same output.
Why do you think  that should be like that? 
With the NaNs?

Making join() more like merge() would be great, IMHO. 
It would make these functions more consistent (and join() would actually do what I want). 

I regularly stumble over that issue, because to me it is quite unintuitive.
Can you explain to me why the current behavior is desirable?
 Agreed that it's unintuitive ;)

From what I can tell, `left.join(right)` is supposed to be shorthand for `pd.merge(left, right, left_index=True, right_index=True)`. The `on` keyword seems a bit strange to me (maybe it was added later).

Personally I never use `.join`, and avoid mentioning it when teaching. My recommendation is
- use `concat` for merging/joining by index
- use `.merge` for database style joins, possibly on an index, possibly on columns.

Anyways, we can't change the behavior now. It's working as documented (even though the documented behavior is strange in this case).
 not sure what you are trying to do here. `.join` works as expected.
