improve documentation and defaults