Document the public api

While working with the API, i couldn't help but notice the lack of documentation. I talked with @glennw on IRC and he explained me a lot of details which i wrote down, so that new contributors will learn from my mistakes. I also tried to explain the relationship between the different parts of the API.

It's still a bit rough but it's something.
There's an equivalent PR for webrender as well.