misc code improvements, additional documentation/writeup