From ebce6346ab9f8c2fa3998da38569a437cdd5c0ea Mon Sep 17 00:00:00 2001 From: Richard Davey Date: Tue, 12 Sep 2017 17:08:43 +0100 Subject: [PATCH] Lets get this comments show on the road --- v3/comments.js | 54 ++++++ v3/docs/comments.json | 289 +++++++++++++++++++++++++++++++ v3/documentjs.json | 15 ++ v3/package.json | 6 +- v3/src/gameobjects/GameObject.js | 65 +++---- 5 files changed, 383 insertions(+), 46 deletions(-) create mode 100644 v3/comments.js create mode 100644 v3/docs/comments.json create mode 100644 v3/documentjs.json diff --git a/v3/comments.js b/v3/comments.js new file mode 100644 index 000000000..ad627257d --- /dev/null +++ b/v3/comments.js @@ -0,0 +1,54 @@ +// https://github.com/jonschlinkert/extract-comments +// https://github.com/eslint/doctrine +// https://nodejs.org/api/fs.html +// https://github.com/jprichardson/node-fs-extra + +var fs = require('fs-extra'); +var extract = require('extract-comments'); +var beautify = require('json-beautify'); +var doctrine = require('doctrine'); + +var source = './src/gameobjects/GameObject.js'; +var dest = './docs/comments.json'; + +var doctrineOptions = { + unwrap: true, + recoverable: true, + sloppy: true, + lineNumbers: true +}; + +fs.readFile(source, 'utf8', (err, data) => { + + if (err) + { + throw err; + } + + var comments = []; + var blocks = extract.block(data); + + for (var i = 0; i < blocks.length; i++) + { + var block = blocks[i]; + + comments.push(doctrine.parse(block.value, doctrineOptions)); + } + + // comments = JSON.stringify(comments); + comments = beautify(comments, null, 2, 100); // just for debugging really + + fs.writeFile(dest, comments, { encoding: 'utf8', flag: 'w' }, function (error) { + + if (error) + { + throw error; + } + else + { + console.log('Comments written'); + } + + }); + +}); diff --git a/v3/docs/comments.json b/v3/docs/comments.json new file mode 100644 index 000000000..25606de88 --- /dev/null +++ b/v3/docs/comments.json @@ -0,0 +1,289 @@ +[ + { + "description": "The base GameObject class that all Game Objects extend.", + "tags": [ + { + "title": "class", + "description": null, + "lineNumber": 3, + "type": null, + "name": "GameObject" + }, + { + "title": "param", + "description": "The Scene to which this Game Object belongs.", + "lineNumber": 5, + "type": { "type": "NameExpression", "name": "Scene" }, + "name": "scene" + }, + { + "title": "param", + "description": "A textual representation of the Game Object.", + "lineNumber": 6, + "type": { "type": "NameExpression", "name": "String" }, + "name": "type" + } + ] + }, + { + "description": "The Scene to which this Game Object belongs.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "type": { "type": "NameExpression", "name": "Scene" }, + "name": "scene" + } + ] + }, + { + "description": "A textual representation of this Game Object.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "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.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "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.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Boolean" } }, + "name": "active", + "default": "true" + } + ] + }, + { + "description": "The Tab Index of this Game Object.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "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.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "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", + "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" } }, + "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.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "type": { "type": "OptionalType", "expression": { "type": "NameExpression", "name": "Number" } }, + "name": "cameraFilter", + "default": "0" + }, + { "title": "private", "description": null, "lineNumber": 4 } + ] + }, + { + "description": "If this Game Object is enabled for input then this property will contain a Phaser.Input.InteractiveObject reference.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "type": { + "type": "OptionalType", + "expression": { + "type": "UnionType", + "elements": [ + { "type": "NameExpression", "name": "Phaser.Input.InteractiveObject" }, + { "type": "NullLiteral" } + ] + } + }, + "name": "input", + "default": "null" + } + ] + }, + { + "description": "If this Game Object is enabled for physics then this property will contain a reference to a Physics Body.", + "tags": [ + { + "title": "property", + "description": null, + "lineNumber": 3, + "type": { + "type": "OptionalType", + "expression": { + "type": "UnionType", + "elements": [ + { "type": "NameExpression", "name": "Phaser.Physics.Body" }, + { "type": "NullLiteral" } + ] + } + }, + "name": "body", + "default": "null" + } + ] + }, + { + "description": "Sets the `active` property of this Game Object and returns this Game Object for further chaining.", + "tags": [ + { "title": "method", "description": null, "lineNumber": 3, "name": "GameObject#setActive" }, + { + "title": "param", + "description": "True if this Game Object should be set as active, false if not.", + "lineNumber": 5, + "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.", + "lineNumber": 7, + "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": "return", + "description": "A JSON representation of the Game Object.", + "lineNumber": 5, + "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": "return", + "description": "True if the Game Object should be rendered, otherwise false.", + "lineNumber": 5, + "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" } ] + } +] \ No newline at end of file diff --git a/v3/documentjs.json b/v3/documentjs.json new file mode 100644 index 000000000..0bbd54fc8 --- /dev/null +++ b/v3/documentjs.json @@ -0,0 +1,15 @@ +{ + "versionDest": "<%= version %>", + "defaultVersion": "3.0.0", + "defaultDest": "./docs", + "versions": { + "3.0.0": { + "source": "./src", + "sites": { + "docs": { + "glob" : "src/**/*.{js,md}" + } + } + } + } +} \ No newline at end of file diff --git a/v3/package.json b/v3/package.json index 4d56695cc..59a923e43 100644 --- a/v3/package.json +++ b/v3/package.json @@ -1,6 +1,4 @@ { - "//": "git tag 3.0.0-beta.1", - "//": "git push", "//": "npm publish ---tag beta", "name": "phaser", "version": "3.0.0-beta.1", @@ -36,11 +34,15 @@ "web audio" ], "devDependencies": { + "doctrine": "^2.0.0", "eslint": "^4.3.0", "fs-extra": "^4.0.0", "uglifyjs-webpack-plugin": "^0.4.6", "uuid": "^3.1.0", "webpack": "^3.4.1", "webpack-shell-plugin": "^0.5.0" + }, + "dependencies": { + "extract-comments": "^0.10.1" } } diff --git a/v3/src/gameobjects/GameObject.js b/v3/src/gameobjects/GameObject.js index 6b0fe5563..e6361cdcc 100644 --- a/v3/src/gameobjects/GameObject.js +++ b/v3/src/gameobjects/GameObject.js @@ -19,48 +19,42 @@ var GameObject = new Class({ /** * The Scene to which this Game Object belongs. * - * @property - * @type {Scene} + * @property {Scene} scene */ this.scene = scene; /** * A textual representation of this Game Object. * - * @property - * @type {string} + * @property {String} type */ this.type = type; /** * The name of this Game Object. Blank by default and not populated by Phaser. Left for developers use. * - * @property - * @type {String} + * @property {String} [name=''] */ this.name = ''; /** * The active state of this Game Object. A Game Object with an active state of `true` is processed by the UpdateList. * - * @property - * @type {Boolean} + * @property {Boolean} [active=true] */ this.active = true; /** * The Tab Index of this Game Object. * - * @property - * @type {Number} + * @property {Integer} [tabIndex=-1] */ this.tabIndex = -1; /** * A proxy to the Data class. It allows you to store and query key/value paired information specific to this Game Object. * - * @property - * @type {DataProxy} + * @property {DataProxy} data */ this.data = new DataProxy(scene, this); @@ -69,8 +63,7 @@ var GameObject = new Class({ * Structure: 0001 | 0010 | 0100 | 1000 * The components: Visible, Alpha, Transform and Texture set bits in this mask respectively * - * @property - * @type {Number} + * @property {Integer} [renderMask=15] * @private */ this.renderMask = 15; @@ -78,8 +71,7 @@ var GameObject = new Class({ /** * The flags that the renderMask uses to determine if the Game Object will render or not. * - * @property - * @type {Number} + * @property {Integer} [renderFlags=15] * @private */ this.renderFlags = 15; @@ -87,8 +79,7 @@ var GameObject = new Class({ /** * A bitmask that controls if this Game Object is drawn by a Camera or not. * - * @property - * @type {Number} + * @property {Number} [cameraFilter=0] * @private */ this.cameraFilter = 0; @@ -96,37 +87,28 @@ var GameObject = new Class({ /** * If this Game Object is enabled for input then this property will contain a Phaser.Input.InteractiveObject reference. * - * @property - * @type {Phaser.Input.InteractiveObject|null} + * @property {Phaser.Input.InteractiveObject|null} [input=null] */ this.input = null; /** * If this Game Object is enabled for physics then this property will contain a reference to a Physics Body. * - * @property - * @type {Phaser.Physics.Body|null} + * @property {Phaser.Physics.Body|null} [body=null] */ this.body = null; - /** - * Should this Game Object trigger a Scene level z-depth sort? - * Automatically set by various components but can also be set manually as required. - * - * @property - * @type {Boolean} - */ + // Tell the Scene to re-sort the children this.scene.sys.sortChildrenFlag = true; }, /** * Sets the `active` property of this Game Object and returns this Game Object for further chaining. * - * @method setActive - * @memberof GameObject# + * @method GameObject#setActive * * @param {Boolean} value - True if this Game Object should be set as active, false if not. - * @returns {this} + * @return {GameObject} This GameObject. */ setActive: function (value) { @@ -138,11 +120,10 @@ var GameObject = new Class({ /** * Sets the `name` property of this Game Object and returns this Game Object for further chaining. * - * @method setName - * @memberof GameObject# + * @method GameObject#setName * * @param {String} value - The name to be given to this Game Object. - * @returns {this} + * @return {GameObject} This GameObject. */ setName: function (value) { @@ -154,12 +135,11 @@ var GameObject = new Class({ /** * Pass this Game Object to the Input Manager to enable it for Input. * - * @method setInteractive - * @memberof GameObject# + * @method GameObject#setInteractive * * @param {[type]} [shape] - A geometric shape that defines the hit area for the Game Object. If not specified a Rectangle will be used. * @param {Function} [callback] - A callback to be invoked when the Game Object is interacted with. - * @returns {this} + * @return {GameObject} This GameObject. */ setInteractive: function (shape, callback) { @@ -176,8 +156,7 @@ var GameObject = new Class({ /** * Returns a JSON representation of the Game Object. * - * @method toJSON - * @memberof GameObject# + * @method GameObject#toJSON * * @return {Object} A JSON representation of the Game Object. */ @@ -189,8 +168,7 @@ var GameObject = new Class({ /** * Compares the renderMask with the renderFlags to see if this Game Object will render or not. * - * @method willRender - * @memberof GameObject# + * @method GameObject#willRender * * @return {Boolean} True if the Game Object should be rendered, otherwise false. */ @@ -206,8 +184,7 @@ var GameObject = new Class({ * 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. * - * @method destroy - * @memberof GameObject# + * @method GameObject#destroy */ destroy: function () {