Join code is difficult to read

[AndrewSisley]

Please either rework it a little bit, or go through it very carefully and document it so that maintainers can understand why it is doing what it is doing. Be careful as it is quite a complex area, and different bits seem to represent different things depending on context.

Review the tests before starting any code change, we've had a few bugs here recently, and historically we have had quite poor coverage here.