add docs, rearrange methods, dry up some helpers
renamed change log