Improved documentation for DataFrame.join
closes #12188 

I modified the description in DataFrame.join to make clear the difference with DataFrame.merge, also added examples.

can you update
 Done, sorry for the delay.
 pls rebase/update
 Sorry for the delay, I've been working to meet some deadlines for a project. I'll update in the next few days.
 can you rebase/update
 can you update according to comments
 can you rebase / update?
 I think the documentation is clear now. There are 3 examples, one using the dataframes original indexes and two joining using the key columns, the first one setting key as the index in both and the second one using on.
 thanks @edublancas nice improvement!
