more docs, and a small bug