document (and slightly refactor) extended part of the main interface