Added javadoc

Hopefully that's a good start... 
We can leave it for now and see how it goes.  It's not strictly an issue with the javadoc anyway - I'm just concerned it might cause some confusion later on - we can cross that bridge when we come to it however.