lots more Javadoc for the API.