cleaned up some comments / introduced some javadocs. Also added some TODO:'s about method designs