Skip to content

Commit 803f54a

Browse files
photonstormphotonstorm
committed
Added jsdocs.
1 parent 00382bf commit 803f54a

7 files changed

Lines changed: 162 additions & 49 deletions

File tree

‎.eslintrc.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@
99
"WEBGL_RENDERER": true,
1010
"CANVAS_RENDERER": true,
1111
"Phaser": true,
12-
"p2": true
12+
"p2": true,
13+
"ActiveXObject": true
1314
},
1415
"rules": {
1516

‎src/dom/AddToDOM.js‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
/**
2-
* [description]
2+
* Adds the given element to the DOM. If a parent is provided the element is added as a child of the parent, providing it was able to access it.
3+
* If no parent was given or falls back to using `document.body`.
34
*
45
* @function Phaser.Dom.AddToDOM
56
* @since 3.0.0
67
*
7-
* @param {any} element - [description]
8-
* @param {any} parent - [description]
8+
* @param {object} element - The element to be added to the DOM. Usually a Canvas object.
9+
* @param {string|object} [parent] - The parent in which to add the element. Can be a string which is passed to `getElementById` or an actual DOM object.
910
* @param {boolean} [overflowHidden=true] - [description]
1011
*
11-
* @return {any} [description]
12+
* @return {object} The element that was added to the DOM.
1213
*/
1314
var AddToDOM = function (element, parent, overflowHidden)
1415
{

‎src/dom/DOMContentLoaded.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@ var OS = require('../device/OS');
33
var isBooted = false;
44

55
/**
6-
* [description]
6+
* Inspects the readyState of the document. If the document is already complete then it invokes the given callback.
7+
* If not complete it sets up several event listeners such as `deviceready`, and once those fire, it invokes the callback.
8+
* Called automatically by the Phaser.Game instance. Should not usually be access directly.
79
*
810
* @function Phaser.Dom.DOMContentLoaded
911
* @since 3.0.0

‎src/dom/ParseXML.js‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
/**
2-
* [description]
2+
* Takes the given data string and parses it as XML.
3+
* First tries to use the window.DOMParser and reverts to the Microsoft.XMLDOM if that fails.
4+
* The parsed XML object is returned, or `null` if there was an error while parsing the data.
35
*
46
* @function Phaser.Dom.ParseXML
57
* @since 3.0.0
68
*
79
* @param {string} data - The XML source stored in a string.
810
*
9-
* @return {any} [description]
11+
* @return {any} The parsed XML data, or `null` if the data could not be parsed.
1012
*/
1113
var ParseXML = function (data)
1214
{

‎src/dom/RemoveFromDOM.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/**
2-
* [description]
2+
* Attempts to remove the element from its parentNode in the DOM.
33
*
44
* @function Phaser.Dom.RemoveFromDOM
55
* @since 3.0.0
66
*
7-
* @param {any} element - [description]
7+
* @param {any} element - The DOM element to remove from its parent node.
88
*/
99
var RemoveFromDOM = function (element)
1010
{

‎src/dom/RequestAnimationFrame.js‎

Lines changed: 125 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,149 @@
1+
var Class = require('../utils/Class');
12
var NOOP = require('../utils/NOOP');
23

3-
// Abstracts away the use of RAF or setTimeOut for the core game update loop.
4-
var RequestAnimationFrame = function ()
5-
{
6-
// @property {boolean} isRunning - true if RequestAnimationFrame is running, otherwise false.
7-
this.isRunning = false;
4+
var RequestAnimationFrame = new Class({
85

9-
this.callback = NOOP;
6+
initialize:
107

11-
this.tick = 0;
8+
/**
9+
* Abstracts away the use of RAF or setTimeOut for the core game update loop.
10+
* This is invoked automatically by the Phaser.Game instance.
11+
*
12+
* @class RequestAnimationFrame
13+
* @memberOf Phaser.DOM
14+
* @constructor
15+
* @since 3.0.0
16+
*/
17+
function RequestAnimationFrame ()
18+
{
19+
/**
20+
* True if RequestAnimationFrame is running, otherwise false.
21+
*
22+
* @property {boolean} isRunning
23+
* @default false
24+
* @since 3.0.0
25+
*/
26+
this.isRunning = false;
1227

13-
// @property {boolean} isSetTimeOut - True if the browser is using setTimeout instead of rAf.
14-
this.isSetTimeOut = false;
28+
/**
29+
* The callback to be invoked each step.
30+
*
31+
* @property {function} callback
32+
* @since 3.0.0
33+
*/
34+
this.callback = NOOP;
1535

16-
// @property {number} timeOutID - The callback setTimeout or rAf callback ID used when calling cancel.
17-
this.timeOutID = null;
36+
/**
37+
* The most recent timestamp. Either a DOMHighResTimeStamp under RAF or `Date.now` under SetTimeout.
38+
*
39+
* @property {DOMHighResTimeStamp|number} tick
40+
* @default 0
41+
* @since 3.0.0
42+
*/
43+
this.tick = 0;
44+
45+
/**
46+
* True if the step is using setTimeout instead of RAF.
47+
*
48+
* @property {boolean} isSetTimeOut
49+
* @default false
50+
* @since 3.0.0
51+
*/
52+
this.isSetTimeOut = false;
53+
54+
/**
55+
* The setTimeout or RAF callback ID used when canceling them.
56+
*
57+
* @property {?number} timeOutID
58+
* @default null
59+
* @since 3.0.0
60+
*/
61+
this.timeOutID = null;
62+
63+
/**
64+
* The previous time the step was called.
65+
*
66+
* @property {number} lastTime
67+
* @default 0
68+
* @since 3.0.0
69+
*/
70+
this.lastTime = 0;
1871

19-
var _this = this;
72+
var _this = this;
2073

21-
// timestamp = DOMHighResTimeStamp
22-
var step = function (timestamp)
23-
{
24-
_this.tick = timestamp;
74+
/**
75+
* The RAF step function.
76+
* Updates the local tick value, invokes the callback and schedules another call to requestAnimationFrame.
77+
*
78+
* @property {function} step
79+
* @since 3.0.0
80+
*/
81+
this.step = function step (timestamp)
82+
{
83+
// DOMHighResTimeStamp
84+
_this.lastTime = _this.tick;
2585

26-
_this.callback(timestamp);
86+
_this.tick = timestamp;
2787

28-
_this.timeOutID = window.requestAnimationFrame(step);
29-
};
88+
_this.callback(timestamp);
3089

31-
var stepTimeout = function ()
32-
{
33-
var d = Date.now();
90+
_this.timeOutID = window.requestAnimationFrame(step);
91+
};
3492

35-
_this.tick = d;
93+
/**
94+
* The SetTimeout step function.
95+
* Updates the local tick value, invokes the callback and schedules another call to setTimeout.
96+
*
97+
* @property {function} stepTimeout
98+
* @since 3.0.0
99+
*/
100+
this.stepTimeout = function stepTimeout ()
101+
{
102+
var d = Date.now();
36103

37-
_this.callback(d);
104+
var delay = Math.max(16 + _this.lastTime - d, 0);
38105

39-
_this.timeOutID = window.setTimeout(stepTimeout, _this.timeToCall);
40-
};
106+
_this.lastTime = _this.tick;
41107

42-
this.step = step;
43-
this.stepTimeout = stepTimeout;
44-
};
108+
_this.tick = d;
45109

46-
RequestAnimationFrame.prototype.constructor = RequestAnimationFrame;
110+
_this.callback(d);
47111

48-
RequestAnimationFrame.prototype = {
112+
_this.timeOutID = window.setTimeout(stepTimeout, delay);
113+
};
114+
},
49115

50-
// Starts the requestAnimationFrame running or setTimeout if unavailable in browser
116+
/**
117+
* Starts the requestAnimationFrame or setTimeout process running.
118+
*
119+
* @method Phaser.DOM.RequestAnimationFrame#start
120+
* @since 3.0.0
121+
*
122+
* @param {function} callback - The callback to invoke each step.
123+
* @param {boolean} forceSetTimeOut - Should it use SetTimeout, even if RAF is available?
124+
*/
51125
start: function (callback, forceSetTimeOut)
52126
{
127+
if (this.isRunning)
128+
{
129+
return;
130+
}
131+
53132
this.callback = callback;
54133

55134
this.isSetTimeOut = forceSetTimeOut;
56135

57136
this.isRunning = true;
58137

59-
var _this = this;
60-
61-
this.timeOutID = (forceSetTimeOut) ? window.setTimeout(_this.stepTimeout, 0) : window.requestAnimationFrame(_this.step);
138+
this.timeOutID = (forceSetTimeOut) ? window.setTimeout(this.stepTimeout, 0) : window.requestAnimationFrame(this.step);
62139
},
63140

64-
// Stops the requestAnimationFrame from running.
141+
/**
142+
* Stops the requestAnimationFrame or setTimeout from running.
143+
*
144+
* @method Phaser.DOM.RequestAnimationFrame#stop
145+
* @since 3.0.0
146+
*/
65147
stop: function ()
66148
{
67149
this.isRunning = false;
@@ -76,13 +158,19 @@ RequestAnimationFrame.prototype = {
76158
}
77159
},
78160

161+
/**
162+
* Stops the step from running and clears the callback reference.
163+
*
164+
* @method Phaser.DOM.RequestAnimationFrame#destroy
165+
* @since 3.0.0
166+
*/
79167
destroy: function ()
80168
{
81169
this.stop();
82170

83171
this.callback = NOOP;
84172
}
85173

86-
};
174+
});
87175

88176
module.exports = RequestAnimationFrame;

‎src/events/EventEmitter.js‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,43 @@ var Class = require('../utils/Class');
22
var EE = require('eventemitter3');
33
var PluginManager = require('../plugins/PluginManager');
44

5-
// Phaser.EventEmitter
6-
75
var EventEmitter = new Class({
86

97
Extends: EE,
108

119
initialize:
1210

11+
/**
12+
* EventEmitter is a Scene Systems plugin compatible version of eventemitter3.
13+
*
14+
* @class EventEmitter
15+
* @extends eventemitter3
16+
* @memberOf Phaser.Events
17+
* @constructor
18+
* @since 3.0.0
19+
*/
1320
function EventEmitter ()
1421
{
1522
EE.call(this);
1623
},
1724

25+
/**
26+
* Removes all listeners.
27+
*
28+
* @method Phaser.Events.EventEmitter#shutdown
29+
* @since 3.0.0
30+
*/
1831
shutdown: function ()
1932
{
2033
this.removeAllListeners();
2134
},
2235

36+
/**
37+
* Removes all listeners.
38+
*
39+
* @method Phaser.Events.EventEmitter#destroy
40+
* @since 3.0.0
41+
*/
2342
destroy: function ()
2443
{
2544
this.removeAllListeners();

0 commit comments

Comments
 (0)