fixed misleading doc-comments; revised README.md.