We have gotten inspiration from lots of places for the API reference. We know the explanations of things need to get better, and we would love to include examples for everything. Improving it is going to be a long term project though. Stay tuned, we hope to make the experience better with each update!