fixes #1

add some documentation for #1 fixes