Reviewing the code and updating the documentation

[Hachitus]

Basically just go through the code and review the API on bigger level. At the same time update documentation and pick up things that could be changed in the upcoming milestones, so the API is will be more consistent, usable and makes sense. Currently the documentation at least, is a bit out-of-date. The biggest benefit is So we can see that the game engine is heading to correct path and that the documentation can be used.

Some suggestions regarding documentation:
Adding #crossLink, @required, @default, @event and @optional to documentation, where needed