added docs, fixed a failing test due to a crappy corner case in sample.