Docco-style documentation

[chenglou]

#351 cleans up lots of categorization nits and made the docs cleaner. Thanks to that, some of the old sections can now be reduced to a few sentences. I was thinking of taking this occasion to:

1. Fully comment the examples so that it can be processed through Docco.
2. Potentially replace those dangling documentation sentences with fresh, fully-featured examples that do the walkthrough while explaining various points (from the current docs). One example I raised in IRC is that "components are just state machines". Seeing that the whole event explanation above now has its dedicated section, these sentences can be reduced to comments in the said examples.
3. Maybe even better than just Docco, display the live editor side-by-side (or whatever UI works) so that the user can see the example code, play with it while reading the comments beside, and still have a complete ref to the API nearby. At the same time this ensures the examples are well separated into chunks. Imagine a front page, but with examples and comments as docs. This idea is really just a demo of the kinds of things we could do; not saying it should be this way.

1 is a non-brainer even without the Docco processing part; I'm down to do it. I can even design some new examples to replace/complement the old ones so that they expose React's general ideas rather than just demoing small snippets of components. This should eliminate another chunk of the documentation. These examples can live in the repo and the doc page.

The goal I'm thinking of here is to be able to tell people what React is through only examples and API docs, no extra explanation needed. At the end of the day, there shouldn't be much documentation left outside of the examples and the API docs. There are flaws in this approach, mainly that the narrative will have to be from the top to the bottom of the code; but I think React's nature alleviate this. I really have to show an example (thinking of starting with the existing comment ex) to prove this.

And hey, if there are details that don't fit into example comments, cookbook's still there.

I realize this is ambitious, but it seems appealing enough to be suggested. I really believe a good example can eliminate lots of explanations and this is an approach I've taken for my own repos; they seem to work well so far.

[chenglou]

Closing this for now because the changes to the examples can be done gradually