From 3b268569f13b54f77fba6cb020c39653ae64b2f1 Mon Sep 17 00:00:00 2001 From: Richard Davey Date: Wed, 13 Sep 2017 02:02:49 +0100 Subject: [PATCH] More comments work. --- v3/comments.js | 25 ++++ v3/docs/comments.json | 241 ++++++++++++++++--------------- v3/src/gameobjects/GameObject.js | 45 ++++-- 3 files changed, 180 insertions(+), 131 deletions(-) diff --git a/v3/comments.js b/v3/comments.js index ad627257d..1f167e3c1 100644 --- a/v3/comments.js +++ b/v3/comments.js @@ -28,6 +28,30 @@ fs.readFile(source, 'utf8', (err, data) => { var comments = []; var blocks = extract.block(data); +/* + // Example extracted docblock: + + { + "type": "block", + "range": [ 1181, 1414 ], + "loc": { "start": { "line": 37, "column": 8 }, "end": { "line": 42, "column": 11 } }, + "raw": "*\r\n * A textual representation of this Game Object, i.e. `sprite`.\r\n * Used internally by Phaser but is available for your own custom classes to populate.\r\n *\r\n * @property {string} type\r\n ", + "value": "\r\nA textual representation of this Game Object, i.e. `sprite`.\r\nUsed internally by Phaser but is available for your own custom classes to populate.\r\n\r\n@property {string} type", + "code": { + "context": { + "type": "property", + "receiver": "this", + "name": "type", + "value": "type", + "string": "this.type" + }, + "value": "this.type = type;\r", + "line": 44, + "loc": { "start": { "line": 44, "column": 1424 }, "end": { "line": 44, "column": 1442 } } + } + }, +*/ + for (var i = 0; i < blocks.length; i++) { var block = blocks[i]; @@ -37,6 +61,7 @@ fs.readFile(source, 'utf8', (err, data) => { // comments = JSON.stringify(comments); comments = beautify(comments, null, 2, 100); // just for debugging really + // comments = beautify(blocks, null, 2, 100); // just for debugging really fs.writeFile(dest, comments, { encoding: 'utf8', flag: 'w' }, function (error) { diff --git a/v3/docs/comments.json b/v3/docs/comments.json index d8098e3d0..40ca506fe 100644 --- a/v3/docs/comments.json +++ b/v3/docs/comments.json @@ -2,12 +2,8 @@ { "description": "", "tags": [ - { - "title": "author", - "description": "Richard Davey ", - "lineNumber": 1 - }, - { "title": "copyright", "description": "2016 Photon Storm Ltd.", "lineNumber": 2 }, + { "title": "author", "description": "Richard Davey ", "lineNumber": 1 }, + { "title": "copyright", "description": "2017 Photon Storm Ltd.", "lineNumber": 2 }, { "title": "license", "description": "{@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}", @@ -16,163 +12,156 @@ ] }, { - "description": "The base GameObject class that all Game Objects extend.", + "description": "", + "tags": [ + { "title": "include", "description": "Class", "lineNumber": 1 }, + { "title": "include", "description": "Components", "lineNumber": 2 }, + { "title": "include", "description": "DataProxy", "lineNumber": 3 } + ] + }, + { + "description": "The base class that all Game Objects extend.\r\nYou don't create GameObjects directly and they cannot be added to the display list.\r\nInstead, use them as the base for your own custom classes.", "tags": [ { "title": "class", "description": null, - "lineNumber": 3, + "lineNumber": 5, "type": null, "name": "GameObject" }, { "title": "namespace", "description": null, - "lineNumber": 4, + "lineNumber": 6, "type": null, "name": "Phaser.GameObjects" }, - { "title": "constructor", "description": null, "lineNumber": 5, "type": null, "name": null }, + { "title": "constructor", "description": null, "lineNumber": 7, "type": null, "name": null }, { "title": "param", "description": "The Scene to which this Game Object belongs.", - "lineNumber": 7, - "type": { "type": "NameExpression", "name": "Scene" }, + "lineNumber": 9, + "type": { "type": "NameExpression", "name": "Phaser.Scene" }, "name": "scene" }, { "title": "param", - "description": "A textual representation of the Game Object.", - "lineNumber": 8, - "type": { "type": "NameExpression", "name": "String" }, + "description": "A textual representation of the type of Game Object, i.e. `sprite`.", + "lineNumber": 10, + "type": { "type": "NameExpression", "name": "string" }, "name": "type" } ] }, { - "description": "The Scene to which this Game Object belongs.", + "description": "The Scene to which this Game Object belongs.\r\nGame Objects can only belong to one Scene.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "NameExpression", "name": "Scene" }, + "lineNumber": 4, + "type": { "type": "NameExpression", "name": "Phaser.Scene" }, "name": "scene" } ] }, { - "description": "A textual representation of this Game Object.", + "description": "A textual representation of this Game Object, i.e. `sprite`.\r\nUsed internally by Phaser but is available for your own custom classes to populate.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "NameExpression", "name": "String" }, + "lineNumber": 4, + "type": { "type": "NameExpression", "name": "string" }, "name": "type" } ] }, { - "description": "The name of this Game Object. Blank by default and not populated by Phaser. Left for developers use.", + "description": "The name of this Game Object.\r\nEmpty by default and never populated by Phaser, this is left for developers to use.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "String" } }, + "lineNumber": 4, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "string" } }, "name": "name", "default": "''" } ] }, { - "description": "The active state of this Game Object. A Game Object with an active state of `true` is processed by the UpdateList.", + "description": "The active state of this Game Object.\r\nA Game Object with an active state of `true` is processed by the Scenes UpdateList, if added to it.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Boolean" } }, + "lineNumber": 4, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "boolean" } }, "name": "active", "default": "true" } ] }, { - "description": "The Tab Index of this Game Object.", + "description": "The Tab Index of the Game Object.\r\nReserved for future use by plugins and the Input Manager.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Integer" } }, + "lineNumber": 4, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "integer" } }, "name": "tabIndex", "default": "-1" } ] }, { - "description": "A proxy to the Data class. It allows you to store and query key/value paired information specific to this Game Object.", + "description": "A proxy to the Data class.\r\nIt allows you to store, query and get key/value paired information specific to this Game Object.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, + "lineNumber": 4, "type": { "type": "NameExpression", "name": "DataProxy" }, "name": "data" } ] }, { - "description": "The bitmask that determines if the Game Object will render or not.\r\nStructure: 0001 | 0010 | 0100 | 1000\r\nThe components: Visible, Alpha, Transform and Texture set bits in this mask respectively", + "description": "The flags that are compared against `RENDER_MASK` to determine if this Game Object will render or not.\r\nThe bits are 0001 | 0010 | 0100 | 1000 set by the components Visible, Alpha, Transform and Texture respectively.\r\nIf those components are not used by your custom class then you can use this bitmask as you wish.", "tags": [ { "title": "property", "description": null, "lineNumber": 5, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Integer" } }, - "name": "renderMask", - "default": "15" - }, - { "title": "private", "description": null, "lineNumber": 6 } - ] - }, - { - "description": "The flags that the renderMask uses to determine if the Game Object will render or not.", - "tags": [ - { - "title": "property", - "description": null, - "lineNumber": 3, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Integer" } }, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "integer" } }, "name": "renderFlags", "default": "15" - }, - { "title": "private", "description": null, "lineNumber": 4 } + } ] }, { - "description": "A bitmask that controls if this Game Object is drawn by a Camera or not.", + "description": "A bitmask that controls if this Game Object is drawn by a Camera or not.\r\nNot usually set directly. Instead call `Camera.ignore`.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Number" } }, + "lineNumber": 4, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "number" } }, "name": "cameraFilter", "default": "0" }, - { "title": "private", "description": null, "lineNumber": 4 } + { "title": "see", "description": "Phaser.Cameras.Camera.ignore", "lineNumber": 5 } ] }, { - "description": "If this Game Object is enabled for input then this property will contain a Phaser.Input.InteractiveObject reference.", + "description": "If this Game Object is enabled for input then this property will contain an InteractiveObject instance.\r\nNot usually set directly. Instead call `GameObject.setInteractive()`.", "tags": [ { "title": "property", "description": null, - "lineNumber": 3, + "lineNumber": 4, "type": { "type": "OptionalType", "expression": { @@ -185,7 +174,8 @@ }, "name": "input", "default": "null" - } + }, + { "title": "see", "description": "setInteractive", "lineNumber": 5 } ] }, { @@ -211,69 +201,16 @@ ] }, { - "description": "Sets the `active` property of this Game Object and returns this Game Object for further chaining.", + "description": "Sets the `active` property of this Game Object and returns this Game Object for further chaining.\r\nA Game Object with its `active` property set to `true` will be updated by the Scenes UpdateList.", "tags": [ - { "title": "method", "description": null, "lineNumber": 3, "name": "GameObject#setActive" }, + { "title": "method", "description": null, "lineNumber": 4, "name": "setActive" }, { "title": "param", "description": "True if this Game Object should be set as active, false if not.", - "lineNumber": 5, - "type": { "type": "NameExpression", "name": "Boolean" }, + "lineNumber": 6, + "type": { "type": "NameExpression", "name": "boolean" }, "name": "value" }, - { - "title": "return", - "description": "This GameObject.", - "lineNumber": 6, - "type": { "type": "NameExpression", "name": "GameObject" } - } - ] - }, - { - "description": "Sets the `name` property of this Game Object and returns this Game Object for further chaining.", - "tags": [ - { "title": "method", "description": null, "lineNumber": 3, "name": "GameObject#setName" }, - { - "title": "param", - "description": "The name to be given to this Game Object.", - "lineNumber": 5, - "type": { "type": "NameExpression", "name": "String" }, - "name": "value" - }, - { - "title": "return", - "description": "This GameObject.", - "lineNumber": 6, - "type": { "type": "NameExpression", "name": "GameObject" } - } - ] - }, - { - "description": "Pass this Game Object to the Input Manager to enable it for Input.", - "tags": [ - { - "title": "method", - "description": null, - "lineNumber": 3, - "name": "GameObject#setInteractive" - }, - { - "title": "param", - "description": "A geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used.", - "lineNumber": 5, - "type": { - "type": "OptionalType", - "expression": { "type": "ArrayType", "elements": [ { "type": "NameExpression", "name": "type" } ] } - }, - "name": "shape" - }, - { - "title": "param", - "description": "A callback to be invoked when the Game Object is interacted with.", - "lineNumber": 6, - "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Function" } }, - "name": "callback" - }, { "title": "return", "description": "This GameObject.", @@ -282,32 +219,98 @@ } ] }, + { + "description": "Sets the `name` property of this Game Object and returns this Game Object for further chaining.\r\nThe `name` property is not populated by Phaser and is presented for your own use.", + "tags": [ + { "title": "example", "description": "game objects/image/set name.js", "lineNumber": 4 }, + { "title": "tutorial", "description": "game objects/basics", "lineNumber": 5 }, + { "title": "method", "description": null, "lineNumber": 7, "name": "setName" }, + { + "title": "param", + "description": "The name to be given to this Game Object.", + "lineNumber": 9, + "type": { "type": "NameExpression", "name": "string" }, + "name": "value" + }, + { + "title": "return", + "description": "This GameObject.", + "lineNumber": 10, + "type": { "type": "NameExpression", "name": "GameObject" } + } + ] + }, + { + "description": "Pass this Game Object to the Input Manager to enable it for Input.", + "tags": [ + { + "title": "example", + "description": "game objects/image/set interactive.js", + "lineNumber": 3 + }, + { "title": "tutorial", "description": "input/basics", "lineNumber": 4 }, + { "title": "method", "description": null, "lineNumber": 6, "name": "setInteractive" }, + { + "title": "param", + "description": "A geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used.", + "lineNumber": 8, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "any" } }, + "name": "shape" + }, + { + "title": "param", + "description": "A callback to be invoked when the Game Object is interacted with.", + "lineNumber": 9, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "function" } }, + "name": "callback" + }, + { + "title": "return", + "description": "This GameObject.", + "lineNumber": 10, + "type": { "type": "NameExpression", "name": "GameObject" } + } + ] + }, { "description": "Returns a JSON representation of the Game Object.", "tags": [ - { "title": "method", "description": null, "lineNumber": 3, "name": "GameObject#toJSON" }, + { "title": "method", "description": null, "lineNumber": 3, "name": "toJSON" }, { "title": "return", "description": "A JSON representation of the Game Object.", "lineNumber": 5, - "type": { "type": "NameExpression", "name": "Object" } + "type": { "type": "NameExpression", "name": "object" } } ] }, { "description": "Compares the renderMask with the renderFlags to see if this Game Object will render or not.", "tags": [ - { "title": "method", "description": null, "lineNumber": 3, "name": "GameObject#willRender" }, + { "title": "method", "description": null, "lineNumber": 3, "name": "willRender" }, { "title": "return", "description": "True if the Game Object should be rendered, otherwise false.", "lineNumber": 5, - "type": { "type": "NameExpression", "name": "Boolean" } + "type": { "type": "NameExpression", "name": "boolean" } } ] }, { "description": "Destroys this Game Object, removing it from the Display List and Update List.\r\nAlso removes it from the Input and Physics Managers if enabled.\r\nSets the active state to `false`. Use this to remove a Game Object from your game if\r\nyou don't plan to use it again later. If you do wish to use it later then look at using\r\nthe Game Object Pool class instead.", - "tags": [ { "title": "method", "description": null, "lineNumber": 7, "name": "GameObject#destroy" } ] + "tags": [ { "title": "method", "description": null, "lineNumber": 7, "name": "destroy" } ] + }, + { + "description": "The bitmask that `GameObject.renderFlags` is compared against to determine if the Game Object will render or not.", + "tags": [ + { + "title": "constant", + "description": null, + "lineNumber": 3, + "type": { "type": "NameExpression", "name": "integer" }, + "name": "RENDER_MASK" + }, + { "title": "default", "description": null, "lineNumber": 4 } + ] } ] \ No newline at end of file diff --git a/v3/src/gameobjects/GameObject.js b/v3/src/gameobjects/GameObject.js index aba8b64ce..ebdce7ef7 100644 --- a/v3/src/gameobjects/GameObject.js +++ b/v3/src/gameobjects/GameObject.js @@ -31,6 +31,7 @@ var GameObject = new Class({ * Game Objects can only belong to one Scene. * * @property {Phaser.Scene} scene + * @protected */ this.scene = scene; @@ -53,6 +54,7 @@ var GameObject = new Class({ /** * The active state of this Game Object. * A Game Object with an active state of `true` is processed by the Scenes UpdateList, if added to it. + * An active object is one which is having its logic and internal systems updated. * * @property {boolean} [active=true] */ @@ -75,27 +77,29 @@ var GameObject = new Class({ this.data = new DataProxy(scene, this); /** - * The flags that the renderMask uses to determine if the Game Object will render or not. - * Structure: 0001 | 0010 | 0100 | 1000 - * The components Visible, Alpha, Transform and Texture set the bits in this mask respectively + * The flags that are compared against `RENDER_MASK` to determine if this Game Object will render or not. + * The bits are 0001 | 0010 | 0100 | 1000 set by the components Visible, Alpha, Transform and Texture respectively. + * If those components are not used by your custom class then you can use this bitmask as you wish. * * @property {integer} [renderFlags=15] - * @private */ this.renderFlags = 15; /** * A bitmask that controls if this Game Object is drawn by a Camera or not. + * Not usually set directly. Instead call `Camera.ignore`. * * @property {number} [cameraFilter=0] - * @private + * @see Phaser.Cameras.Camera.ignore */ this.cameraFilter = 0; /** - * If this Game Object is enabled for input then this property will contain a Phaser.Input.InteractiveObject reference. + * If this Game Object is enabled for input then this property will contain an InteractiveObject instance. + * Not usually set directly. Instead call `GameObject.setInteractive()`. * * @property {Phaser.Input.InteractiveObject|null} [input=null] + * @see setInteractive */ this.input = null; @@ -112,6 +116,7 @@ var GameObject = new Class({ /** * Sets the `active` property of this Game Object and returns this Game Object for further chaining. + * A Game Object with its `active` property set to `true` will be updated by the Scenes UpdateList. * * @method setActive * @@ -127,6 +132,10 @@ var GameObject = new Class({ /** * Sets the `name` property of this Game Object and returns this Game Object for further chaining. + * The `name` property is not populated by Phaser and is presented for your own use. + * + * @example game objects/image/set name.js + * @tutorial game objects/basics * * @method setName * @@ -143,6 +152,9 @@ var GameObject = new Class({ /** * Pass this Game Object to the Input Manager to enable it for Input. * + * @example game objects/image/set interactive.js + * @tutorial input/basics + * * @method setInteractive * * @param {any} [shape] - A geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used. @@ -186,11 +198,17 @@ var GameObject = new Class({ }, /** - * Destroys this Game Object, removing it from the Display List and Update List. - * Also removes it from the Input and Physics Managers if enabled. - * Sets the active state to `false`. Use this to remove a Game Object from your game if - * you don't plan to use it again later. If you do wish to use it later then look at using - * the Game Object Pool class instead. + * Destroys this Game Object removing it from the Display List and Update List and + * severing all ties to parent resources. + * + * Also removes itself from the Input Manager and Physics Manager if previously enabled. + * + * Use this to remove a Game Object from your game if you don't ever plan to use it again. + * As long as no reference to it exists within your own code it should become free for + * garbage collection by the browser. + * + * If you just want to temporarily disable an object then look at using the + * Game Object Pool instead of destroying it, as destroyed objects cannot be resurrected. * * @method destroy */ @@ -211,6 +229,8 @@ var GameObject = new Class({ this.active = false; + this.data = undefined; + this.scene = undefined; } @@ -219,7 +239,8 @@ var GameObject = new Class({ /** * The bitmask that `GameObject.renderFlags` is compared against to determine if the Game Object will render or not. * - * @constant {integer} [RENDER_MASK=15] + * @constant {integer} RENDER_MASK + * @default */ GameObject.RENDER_MASK = 15;