emberjs/ember.js — pull request #2499 by mixonic (2013-04-19 02:58:03+00:00)
Title: Document run.scheduleOnce, truncate run.once docs. Fixes #2132.

This is a tradeoff to avoid repeating the docs for scheduleOnce on once. Most people may intend to use run.once, but scheeduleOnce is certainly widely enough used to deserve documentation of it's own.

> Schedules a function to run one time in a given queue of the current RunLoop.
> Calling this method with the same queue/target/method combination will have
> no effect (past the initial call).
>
> Note that although you can pass optional arguments these will not be
> considered when looking for duplicates. New arguments will replace previous
> calls.
>
> ```javascript
> Ember.run(function(){
> var sayHi = function() { console.log('hi'); }
> Ember.run.scheduleOnce('afterRender', myContext, sayHi);
> Ember.run.scheduleOnce('afterRender', myContext, sayHi);
> // doFoo will only be executed once, in the afterRender queue of the RunLoop
> });
> ```
>
> Also note that passing an anonymous function to `Ember.run.scheduleOnce` will
> not prevent additional calls with an identical anonymous function from
> scheduling the items multiple times, e.g.:
>
> ```javascript
> function scheduleIt() {
> Ember.run.scheduleOnce('actions', myContext, function() { console.log("Closure"); });
> }
> scheduleIt();
> scheduleIt();
> // "Closure" will print twice, even though we're using `Ember.run.scheduleOnce`,
> // because the function we pass to it is anonymous and won't match the
> // previously scheduled operation.
> ```
>
> Available queues, and their order, can be found at `Ember.run.queues`