documented the public-facing API, renamed several sub-types