lengthy additions to tests & docs