handle empty input better

improve docs and comments.