Doc improvements

I added them as I was reading the code to understand how it works, and where things run; as this involves at least 3 JVMs, it can get quite confusing, and I think added comments help people make understand it better.