massive doc hacking and resulting API improvements