add more documentation; close #1234