diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 000000000..f4d8b9fcb --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,20 @@ +{ + "plugins": ["plugins/markdown"], + "templates": { + "default": { + "includeDate": false, + "outputSourceFiles": false + } + }, + "source": { + "include": ["src"] + }, + "opts": { + "destination": "playground/docs", + "pedantic": true, + "private": true, + "readme": "README.md", + "recurse": true, + "template": "node_modules/docdash" + } +} diff --git a/package-lock.json b/package-lock.json index cfef5582a..6b44d50b4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2442,6 +2442,15 @@ "resolved": "https://registry.npmjs.org/caseless/-/caseless-0.11.0.tgz", "integrity": "sha1-cVuW6phBWTzDMGeSP17GDr2k99c=" }, + "catharsis": { + "version": "0.8.9", + "resolved": "https://registry.npmjs.org/catharsis/-/catharsis-0.8.9.tgz", + "integrity": "sha1-mMyJDKZS3S7w5ws3klMQ/56Q/Is=", + "dev": true, + "requires": { + "underscore-contrib": "~0.3.0" + } + }, "chalk": { "version": "1.1.3", "resolved": "https://registry.npmjs.org/chalk/-/chalk-1.1.3.tgz", @@ -3384,6 +3393,12 @@ "buffer-indexof": "^1.0.0" } }, + "docdash": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/docdash/-/docdash-0.4.0.tgz", + "integrity": "sha1-BcOlDYMYmYFpnuDAdtOjlQ237AA=", + "dev": true + }, "doctrine": { "version": "2.0.0", "resolved": "http://registry.npmjs.org/doctrine/-/doctrine-2.0.0.tgz", @@ -5410,8 +5425,7 @@ "ansi-regex": { "version": "2.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "aproba": { "version": "1.2.0", @@ -5432,14 +5446,12 @@ "balanced-match": { "version": "1.0.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "brace-expansion": { "version": "1.1.11", "bundled": true, "dev": true, - "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -5454,20 +5466,17 @@ "code-point-at": { "version": "1.1.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "concat-map": { "version": "0.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "console-control-strings": { "version": "1.1.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "core-util-is": { "version": "1.0.2", @@ -5584,8 +5593,7 @@ "inherits": { "version": "2.0.3", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "ini": { "version": "1.3.5", @@ -5597,7 +5605,6 @@ "version": "1.0.0", "bundled": true, "dev": true, - "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -5612,7 +5619,6 @@ "version": "3.0.4", "bundled": true, "dev": true, - "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -5620,14 +5626,12 @@ "minimist": { "version": "0.0.8", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "minipass": { "version": "2.2.4", "bundled": true, "dev": true, - "optional": true, "requires": { "safe-buffer": "^5.1.1", "yallist": "^3.0.0" @@ -5646,7 +5650,6 @@ "version": "0.5.1", "bundled": true, "dev": true, - "optional": true, "requires": { "minimist": "0.0.8" } @@ -5727,8 +5730,7 @@ "number-is-nan": { "version": "1.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "object-assign": { "version": "4.1.1", @@ -5740,7 +5742,6 @@ "version": "1.4.0", "bundled": true, "dev": true, - "optional": true, "requires": { "wrappy": "1" } @@ -5826,8 +5827,7 @@ "safe-buffer": { "version": "5.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "safer-buffer": { "version": "2.1.2", @@ -5863,7 +5863,6 @@ "version": "1.0.2", "bundled": true, "dev": true, - "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", @@ -5883,7 +5882,6 @@ "version": "3.0.1", "bundled": true, "dev": true, - "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -5927,14 +5925,12 @@ "wrappy": { "version": "1.0.2", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "yallist": { "version": "3.0.2", "bundled": true, - "dev": true, - "optional": true + "dev": true } } }, @@ -7473,6 +7469,15 @@ "esprima": "^4.0.0" } }, + "js2xmlparser": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/js2xmlparser/-/js2xmlparser-3.0.0.tgz", + "integrity": "sha1-P7YOqgicVED5MZ9RdgzNB+JJlzM=", + "dev": true, + "requires": { + "xmlcreate": "^1.0.1" + } + }, "jsbn": { "version": "0.1.1", "resolved": "http://registry.npmjs.org/jsbn/-/jsbn-0.1.1.tgz", @@ -7610,6 +7615,40 @@ } } }, + "jsdoc": { + "version": "3.5.5", + "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-3.5.5.tgz", + "integrity": "sha512-6PxB65TAU4WO0Wzyr/4/YhlGovXl0EVYfpKbpSroSj0qBxT4/xod/l40Opkm38dRHRdQgdeY836M0uVnJQG7kg==", + "dev": true, + "requires": { + "babylon": "7.0.0-beta.19", + "bluebird": "~3.5.0", + "catharsis": "~0.8.9", + "escape-string-regexp": "~1.0.5", + "js2xmlparser": "~3.0.0", + "klaw": "~2.0.0", + "marked": "~0.3.6", + "mkdirp": "~0.5.1", + "requizzle": "~0.2.1", + "strip-json-comments": "~2.0.1", + "taffydb": "2.6.2", + "underscore": "~1.8.3" + }, + "dependencies": { + "babylon": { + "version": "7.0.0-beta.19", + "resolved": "https://registry.npmjs.org/babylon/-/babylon-7.0.0-beta.19.tgz", + "integrity": "sha512-Vg0C9s/REX6/WIXN37UKpv5ZhRi6A4pjHlpkE34+8/a6c2W1Q692n3hmc+SZG5lKRnaExLUbxtJ1SVT+KaCQ/A==", + "dev": true + }, + "underscore": { + "version": "1.8.3", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.8.3.tgz", + "integrity": "sha1-Tz+1OxBuYJf8+ctBCfKl6b36UCI=", + "dev": true + } + } + }, "jsesc": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-1.3.0.tgz", @@ -7781,6 +7820,15 @@ "integrity": "sha512-s5kLOcnH0XqDO+FvuaLX8DDjZ18CGFk7VygH40QoKPUQhW4e2rvM0rwUq0t8IQDOwYSeLK01U90OjzBTme2QqA==", "dev": true }, + "klaw": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/klaw/-/klaw-2.0.0.tgz", + "integrity": "sha1-WcEo4Nxc5BAgEVEZTuucv4WGUPY=", + "dev": true, + "requires": { + "graceful-fs": "^4.1.9" + } + }, "lcid": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/lcid/-/lcid-1.0.0.tgz", @@ -8273,6 +8321,12 @@ "object-visit": "^1.0.0" } }, + "marked": { + "version": "0.3.19", + "resolved": "https://registry.npmjs.org/marked/-/marked-0.3.19.tgz", + "integrity": "sha512-ea2eGWOqNxPcXv8dyERdSr/6FmzvWwzjMxpfGB/sbMccXoct+xY+YukPD+QTUZwyvK7BZwcr4m21WBOW41pAkg==", + "dev": true + }, "md5.js": { "version": "1.3.4", "resolved": "https://registry.npmjs.org/md5.js/-/md5.js-1.3.4.tgz", @@ -12940,6 +12994,15 @@ "integrity": "sha1-kl0mAdOaxIXgkc8NpcbmlNw9yv8=", "dev": true }, + "requizzle": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/requizzle/-/requizzle-0.2.1.tgz", + "integrity": "sha1-aUPDUwxNmn5G8c3dUcFY/GcM294=", + "dev": true, + "requires": { + "underscore": "~1.6.0" + } + }, "resolve": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.4.0.tgz", @@ -13155,9 +13218,9 @@ } }, "scratch-blocks": { - "version": "0.1.0-prerelease.1532446271", - "resolved": "https://registry.npmjs.org/scratch-blocks/-/scratch-blocks-0.1.0-prerelease.1532446271.tgz", - "integrity": "sha512-5YkzaUK5BUBtNZVcHe57a3zkePaOZNqaWJRRuyZwptI9FMxd4c1phmTX8vS1quQqLwaPPQ8pE4/oZFIqacN3Eg==", + "version": "0.1.0-prerelease.1533046967", + "resolved": "https://registry.npmjs.org/scratch-blocks/-/scratch-blocks-0.1.0-prerelease.1533046967.tgz", + "integrity": "sha512-smSD/KuoIeIHBjtjXapc1Nu/S/344TBSY4S4MIEsCPV+LDGMCufERbxe/00H8hXLXF88LP3uTJ/kqTRZSR08Gg==", "dev": true, "requires": { "exports-loader": "0.6.3", @@ -14366,6 +14429,12 @@ } } }, + "taffydb": { + "version": "2.6.2", + "resolved": "https://registry.npmjs.org/taffydb/-/taffydb-2.6.2.tgz", + "integrity": "sha1-fLy2S1oUG2ou/CxdLGe04VCyomg=", + "dev": true + }, "tap": { "version": "11.1.4", "resolved": "https://registry.npmjs.org/tap/-/tap-11.1.4.tgz", @@ -14837,6 +14906,15 @@ "integrity": "sha1-izixDKze9jM3uLJOT/htRa6lKag=", "dev": true }, + "underscore-contrib": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/underscore-contrib/-/underscore-contrib-0.3.0.tgz", + "integrity": "sha1-ZltmwkeD+PorGMn4y7Dix9SMJsc=", + "dev": true, + "requires": { + "underscore": "1.6.0" + } + }, "unicode-length": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/unicode-length/-/unicode-length-1.0.3.tgz", @@ -15998,6 +16076,12 @@ "integrity": "sha1-Ey7mPS7FVlxVfiD0wi35rKaGsQ0=", "dev": true }, + "xmlcreate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/xmlcreate/-/xmlcreate-1.0.2.tgz", + "integrity": "sha1-+mv3YqYKQT+z3Y9LA8WyaSONMI8=", + "dev": true + }, "xmlhttprequest-ssl": { "version": "1.5.4", "resolved": "https://registry.npmjs.org/xmlhttprequest-ssl/-/xmlhttprequest-ssl-1.5.4.tgz", diff --git a/package.json b/package.json index f3eec486a..4b452ea4c 100644 --- a/package.json +++ b/package.json @@ -12,9 +12,10 @@ "main": "./dist/node/scratch-vm.js", "browser": "./src/index.js", "scripts": { - "build": "webpack --progress --colors --bail", + "build": "npm run docs && webpack --progress --colors --bail", "coverage": "tap ./test/{unit,integration}/*.js --coverage --coverage-report=lcov", "deploy": "touch playground/.nojekyll && gh-pages -t -d playground -m \"Build for $(git log --pretty=format:%H -n1)\"", + "docs": "jsdoc -c .jsdoc.json", "extract:core": "mkdirp translations/core && format-message extract --out-file translations/core/en.json src/extensions/**/index.js", "i18n:src": "npm run extract:core", "lint": "eslint . && format-message lint src/**/*.js", @@ -23,7 +24,7 @@ "tap": "tap ./test/{unit,integration}/*.js", "tap:unit": "tap ./test/unit/*.js", "tap:integration": "tap ./test/integration/*.js", - "test": "npm run lint && npm run tap", + "test": "npm run lint && npm run docs && npm run tap", "watch": "webpack --progress --colors --watch", "version": "json -f package.json -I -e \"this.repository.sha = '$(git log -n1 --pretty=format:%H)'\"" }, @@ -54,6 +55,7 @@ "babel-loader": "^7.0.0", "babel-preset-env": "^1.6.1", "copy-webpack-plugin": "^4.5.1", + "docdash": "^0.4.0", "eslint": "^5.0.1", "eslint-config-scratch": "^5.0.0", "expose-loader": "0.7.5", @@ -61,6 +63,7 @@ "format-message-cli": "5.2.1", "gh-pages": "^1.1.0", "in-publish": "^2.0.0", + "jsdoc": "^3.5.5", "json": "^9.0.4", "lodash.defaultsdeep": "4.6.0", "pngjs": "^3.3.2", diff --git a/src/dispatch/shared-dispatch.js b/src/dispatch/shared-dispatch.js index 1e4785bce..8e665c1d9 100644 --- a/src/dispatch/shared-dispatch.js +++ b/src/dispatch/shared-dispatch.js @@ -30,7 +30,7 @@ class SharedDispatch { * List of callback registrations for promises waiting for a response from a call to a service on another * worker. A callback registration is an array of [resolve,reject] Promise functions. * Calls to local services don't enter this list. - * @type {Array.<[Function,Function]>} + * @type {Array.} */ this.callbacks = []; diff --git a/src/engine/runtime.js b/src/engine/runtime.js index 9a4ed3972..5847f6ebc 100644 --- a/src/engine/runtime.js +++ b/src/engine/runtime.js @@ -41,7 +41,7 @@ const defaultBlockPackages = { /** * Information used for converting Scratch argument types into scratch-blocks data. - * @type {object.}} + * @type {object.} */ const ArgumentTypeMap = (() => { const map = {}; diff --git a/src/extensions/scratch3_music/index.js b/src/extensions/scratch3_music/index.js index 1ef4d6942..550dff1d6 100644 --- a/src/extensions/scratch3_music/index.js +++ b/src/extensions/scratch3_music/index.js @@ -165,7 +165,7 @@ class Scratch3MusicBlocks { /** * An array of info about each drum. - * @type {object[]} an array of objects. + * @type {object[]} * @param {string} name - the translatable name to display in the drums menu. * @param {string} fileName - the name of the audio file containing the drum sound. */ @@ -320,7 +320,7 @@ class Scratch3MusicBlocks { /** * An array of info about each instrument. - * @type {object[]} an array of objects. + * @type {object[]} * @param {string} name - the translatable name to display in the instruments menu. * @param {string} dirName - the name of the directory containing audio samples for this instrument. * @param {number} [releaseTime] - an optional duration for the release portion of each note. diff --git a/src/extensions/scratch3_video_sensing/index.js b/src/extensions/scratch3_video_sensing/index.js index 6764c1ab2..3e2dd1231 100644 --- a/src/extensions/scratch3_video_sensing/index.js +++ b/src/extensions/scratch3_video_sensing/index.js @@ -260,7 +260,7 @@ class Scratch3VideoSensingBlocks { /** * An array of choices of whether a reporter should return the frame's * motion amount or direction. - * @type {object[]} an array of objects + * @type {object[]} * @param {string} name - the translatable name to display in sensor * attribute menu * @param {string} value - the serializable value of the attribute @@ -292,7 +292,7 @@ class Scratch3VideoSensingBlocks { /** * An array of info about the subject choices. - * @type {object[]} an array of objects + * @type {object[]} * @param {string} name - the translatable name to display in the subject menu * @param {string} value - the serializable value of the subject */ @@ -328,7 +328,7 @@ class Scratch3VideoSensingBlocks { /** * An array of info on video state options for the "turn video [STATE]" block. - * @type {object[]} an array of objects + * @type {object[]} * @param {string} name - the translatable name to display in the video state menu * @param {string} value - the serializable value stored in the block */ diff --git a/src/extensions/scratch3_wedo2/index.js b/src/extensions/scratch3_wedo2/index.js index ad1fd14d0..1b20f245a 100644 --- a/src/extensions/scratch3_wedo2/index.js +++ b/src/extensions/scratch3_wedo2/index.js @@ -205,7 +205,7 @@ class WeDo2 { /** * The motors which this WeDo 2.0 could possibly have. - * @type {[WeDo2Motor]} + * @type {WeDo2Motor[]} * @private */ this._motors = [new WeDo2Motor(this, 0), new WeDo2Motor(this, 1)]; diff --git a/src/serialization/sb2.js b/src/serialization/sb2.js index 27cd0c042..b07d0f7a4 100644 --- a/src/serialization/sb2.js +++ b/src/serialization/sb2.js @@ -122,7 +122,7 @@ const flatten = function (blocks) { * which block they should attach to. * @param {int} commentIndex The current index of the top block in this list if it were in a flattened * list of all blocks for the target - * @return {[Array., int]} Tuple where first item is the Scratch VM-format block list, and + * @return {Array|int>} Tuple where first item is the Scratch VM-format block list, and * second item is the updated comment index */ const parseBlockList = function (blockList, addBroadcastMsg, getVariableId, extensions, comments, commentIndex) { @@ -724,7 +724,7 @@ const specMapBlock = function (block) { * which block they should attach to. * @param {int} commentIndex The comment index for the block to be parsed if it were in a flattened * list of all blocks for the target - * @return {[object, int]} Tuple where first item is the Scratch VM-format block (or null if unsupported object), + * @return {Array.} Tuple where first item is the Scratch VM-format block (or null if unsupported object), * and second item is the updated comment index (after this block and its children are parsed) */ const parseBlock = function (sb2block, addBroadcastMsg, getVariableId, extensions, comments, commentIndex) { diff --git a/src/util/string-util.js b/src/util/string-util.js index b71054a04..1d8f18d4f 100644 --- a/src/util/string-util.js +++ b/src/util/string-util.js @@ -17,7 +17,7 @@ class StringUtil { * Split a string on the first occurrence of a split character. * @param {string} text - the string to split. * @param {string} separator - split the text on this character. - * @returns {[string, string]} - the two parts of the split string, or [text, null] if no split character found. + * @returns {string[]} - the two parts of the split string, or [text, null] if no split character found. * @example * // returns ['foo', 'tar.gz'] * splitFirst('foo.tar.gz', '.'); diff --git a/src/virtual-machine.js b/src/virtual-machine.js index b1b186972..1a1d7c036 100644 --- a/src/virtual-machine.js +++ b/src/virtual-machine.js @@ -936,8 +936,8 @@ class VirtualMachine extends EventEmitter { /** * set the current locale and builtin messages for the VM - * @param {[type]} locale current locale - * @param {[type]} messages builtin messages map for current locale + * @param {!string} locale current locale + * @param {!object} messages builtin messages map for current locale * @returns {Promise} Promise that resolves when all the blocks have been * updated for a new locale (or empty if locale hasn't changed.) */