add some javadoc
add a little explanation *cue the many WTFs*