updated README.md with in-depth API details.
renamed some API debugging helpers for clarity