consider promoting this documentation to class-level javadoc