@gejza maybe you and @b12345 misunderstand the meaning of clear definition of what is this.
What we need from an API reference for a class/functions is what it is used for? what parameters is needed to use it? Do it have some special/amazing features which won't be use in normal cases but maybe you'll need them in some cases -> if yes, what is it? how to use it?
Google is a real programmer's friend these day, i dont know how many times i solved a problems thank to it, but hey, if you think "a few second to figure out what it is" is worse than "several minutes searching google and filter the right answer", then that's ok, no one here have enough power to prevent you from doing that, you're welcome.
@slackmoehrle you've talked about the problem when API is well documented, user will beg more for many examples how to customize something, in the examples. But i dont think it will happen (may be i'm wrong) , those begging will go stretch to forum, and they will wait for the help of other users. For example, it the manual clearly state: red button - launch the nuke, green button - destroy the nuke -> if user want to destroyed a launched nuke, either they try out themselves or ask for other's help, demand the manual to show all the possible is ridiculous, because even the manual cannot predict all the possible.
The Editor is still a need, and many people blame Chukong direction for js, but that's not fair. As @ricardo said, most asian-user is using js/lua, and i think even Chukong using js for most of their games. Then they pour most of their resouces to cocos creator/js is the right choice for their company. What we want now is how to balance out what we need, and what the company need, but that's is the most difficult task, that's why this topic's born.
The c++ port Cocos Creator is coming, that's is really great news (at least to me), but as many people above have said, documents still need to be improved. And the stability, performance on platforms other than ios must be focus.
That's said, i think you guy should plan some way for the user contribute back to the engine, at least for the tutorials/examples part, or to the editor. Because i dont think you guy have enough resources to support for many things