improved documentation and defaults