improve README and code documentation

I cleaned up the README and added more documentation in the code itself. I also added some `TODO:` lines for further enhancements. Can't wait to see them trigger new issues. :smile: