Update javadoc of join functions

Hopefully the new descriptions are clearer and more consistent.