code documentation and improvements