Easel.js docs need improvement

A few days ago, Sebastian DeRossi asked me on Twitter how to improve Easel.js docs. As this is too large for Twitter's 140 characters, here's a short blog post of some issues I found:

1. I was looking for a way to Flip an image and docs don't mention that you can use negative values to scaleX and scaleY. I was really planning to work around this by creating all the required mirror images using ImageMagic and load 2 sets of sprites, when I accidentally found the example using negative values on some blog while searching for something completely different.

2. Say you are a complete beginner like me, and you wish to add a mouse click event handler to Bitmap. You would go into docs, click Bitmap, go to list of events, where it says Click and there are links to DisplayObject and MouseEvent there, but none of those lead to example how to actually use it. Failing this, I first found onClick only to find out that it is deprecated and I should use addEventListener(), without any example how to use it. BTW, I did manage to get onClick to work, but I did not want to use a deprecated function. In the end, I asked on StackOverflow and got a real example how to use addEventListener for mouse events.

3. The thing I'm still confused about, is what is the standard application structure. I.e. how to do the main game loop? In docs, the Getting Started section ends with this:

//Update stage will render next frame
createjs.Ticker.addEventListener("tick", handleTick);

function handleTick() {
    //Circle will move 10 units to the right.
    circle.x += 10;

    //Will cause the circle to wrap back
    if (circle.x > stage.canvas.width) { circle.x = 0; }
    stage.update();
}

Am I supposed to update all my logic in handleTick()? I would create my own functions of course, and call it from there. Should the structure of my program look like this:

createjs.Ticker.addEventListener("tick", handleTick);

function handleTick() {
    updateWorldLogic();
    stage.update();
}

Somewhere else, I found an example like this:

var canvas = document.getElementById("canvas_id");

startGame();
function startGame() {
    stage = new createjs.Stage(canvas);

    // NOTE the following comment, I have NO idea what it means???
    // We want to do some work before we update the canvas,
    // otherwise we could use Ticker.addListener(stage);

    createjs.Ticker.addListener(window);
    createjs.Ticker.useRAF = true;
    createjs.Ticker.setFPS(60);
}

function tick()
{
    // update the stage:
    stage.update();
}

This code works, but I don't understand the difference between:

createjs.Ticker.addListener(window);
createjs.Ticker.addListener(stage);
createjs.Ticker.addEventListener("tick", handleTick);

...and I'm having a hard time getting this clear from the docs.

Tweet to @mbabuskov Milan Babuškov, 2013-05-13