Pretty complicated functionality, could use some brief javadoc to help people down the road.