Merge pull request #1398 from paulkaplan/publish-docs

Publish jsdoc to gh-pages

.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"
+    }
+}

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,
+          "dev": true
-          "optional": true
         },
         "aproba": {
           "version": "1.2.0",
@@ -5432,14 +5446,12 @@
         "balanced-match": {
           "version": "1.0.0",
           "bundled": true,
-          "dev": true,
+          "dev": true
-          "optional": 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,
+          "dev": true
-          "optional": true
         },
         "concat-map": {
           "version": "0.0.1",
           "bundled": true,
-          "dev": true,
+          "dev": true
-          "optional": true
         },
         "console-control-strings": {
           "version": "1.1.0",
           "bundled": true,
-          "dev": true,
+          "dev": true
-          "optional": true
         },
         "core-util-is": {
           "version": "1.0.2",
@@ -5584,8 +5593,7 @@
         "inherits": {
           "version": "2.0.3",
           "bundled": true,
-          "dev": true,
+          "dev": true
-          "optional": 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,
+          "dev": true
-          "optional": 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,
+          "dev": true
-          "optional": 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,
+          "dev": true
-          "optional": 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,
+          "dev": true
-          "optional": true
         },
         "yallist": {
           "version": "3.0.2",
           "bundled": true,
-          "dev": true,
+          "dev": true
-          "optional": 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",
+      "version": "0.1.0-prerelease.1533046967",
-      "resolved": "https://registry.npmjs.org/scratch-blocks/-/scratch-blocks-0.1.0-prerelease.1532446271.tgz",
+      "resolved": "https://registry.npmjs.org/scratch-blocks/-/scratch-blocks-0.1.0-prerelease.1533046967.tgz",
-      "integrity": "sha512-5YkzaUK5BUBtNZVcHe57a3zkePaOZNqaWJRRuyZwptI9FMxd4c1phmTX8vS1quQqLwaPPQ8pE4/oZFIqacN3Eg==",
+      "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",

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",

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.<Function[]>}
          */
         this.callbacks = [];
 

src/engine/runtime.js

@@ -41,7 +41,7 @@ const defaultBlockPackages = {
 
 /**
  * Information used for converting Scratch argument types into scratch-blocks data.
- * @type {object.<ArgumentType, {shadowType: string, fieldType: string}>}}
+ * @type {object.<ArgumentType, {shadowType: string, fieldType: string}>}
  */
 const ArgumentTypeMap = (() => {
     const map = {};

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.

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
      */

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)];

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.<object>, int]} Tuple where first item is the Scratch VM-format block list, and
+ * @return {Array<Array.<object>|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.<object|int>} 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) {

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', '.');

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 {!string} locale       current locale
-     * @param {[type]} messages     builtin messages map for 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.)
      */