add doc comments
better debug messages ; misc improvements