Filled in details in the javadoc for PathHandler

I personally didn't understand some the functions in PathHandler. So after some help from the IRC I wrote out the clearifications in the javadoc for the functions.