Merge pull request #67 from tmickel/feature/eslint-jsdoc

Add .eslintrc rule to check JSDoc syntax

.eslintrc

@@ -8,7 +8,8 @@
         "max-len": [2, 80, 4],
         "semi": [2, "always"],
         "strict": [2, "never"],
-        "no-console": [2, {"allow": ["log", "warn", "error", "groupCollapsed", "groupEnd"]}]
+        "no-console": [2, {"allow": ["log", "warn", "error", "groupCollapsed", "groupEnd"]}],
+        "valid-jsdoc": ["error", {"requireReturn": false}]
     },
     "env": {
         "node": true,

src/blocks/wedo2.js

@@ -41,9 +41,9 @@ WeDo2Blocks.prototype.getPrimitives = function() {
 /**
  * Clamp a value between a minimum and maximum value.
  * @todo move this to a common utility class.
- * @param val The value to clamp.
- * @param min The minimum return value.
- * @param max The maximum return value.
+ * @param {number} val The value to clamp.
+ * @param {number} min The minimum return value.
+ * @param {number} max The maximum return value.
  * @returns {number} The clamped value.
  * @private
  */
@@ -53,9 +53,9 @@ WeDo2Blocks.prototype._clamp = function(val, min, max) {
 
 /**
  * Common implementation for motor blocks.
- * @param direction The direction to turn ('left' or 'right').
- * @param durationSeconds The number of seconds to run.
- * @param util The util instance to use for yielding and finishing.
+ * @param {string} direction The direction to turn ('left' or 'right').
+ * @param {number} durationSeconds The number of seconds to run.
+ * @param {Object} util The util instance to use for yielding and finishing.
  * @private
  */
 WeDo2Blocks.prototype._motorOnFor = function(direction, durationSeconds, util) {
@@ -108,7 +108,7 @@ WeDo2Blocks.prototype.motorSpeed = function(argValues) {
 /**
  * Convert a color name to a WeDo color index.
  * Supports 'mystery' for a random hue.
- * @param colorName The color to retrieve.
+ * @param {string} colorName The color to retrieve.
  * @returns {number} The WeDo color index.
  * @private
  */

src/engine/adapter.js

@@ -52,8 +52,8 @@ function domToBlocks (blocksDOM) {
  * Convert and an individual block DOM to the representation tree.
  * Based on Blockly's `domToBlockHeadless_`.
  * @param {Element} blockDOM DOM tree for an individual block.
- * @param {Boolean} isTopBlock Whether blocks at this level are "top blocks."
  * @param {Object} blocks Collection of blocks to add to.
+ * @param {Boolean} isTopBlock Whether blocks at this level are "top blocks."
  */
 function domToBlock (blockDOM, blocks, isTopBlock) {
     // Block skeleton.

src/engine/blocks.js

@@ -91,11 +91,11 @@ Blocks.prototype.getOpcode = function (id) {
  */
 
 Blocks.prototype.generateBlockListener = function (isFlyout, opt_runtime) {
+    var instance = this;
     /**
      * The actual generated block listener.
-     * @param {Object} Blockly "block" event
+     * @param {Object} e Blockly "block" event
      */
-    var instance = this;
     return function (e) {
         // Validate event
         if (typeof e !== 'object') return;
@@ -149,6 +149,7 @@ Blocks.prototype.generateBlockListener = function (isFlyout, opt_runtime) {
 /**
  * Block management: create blocks and stacks from a `create` event
  * @param {!Object} block Blockly create event to be processed
+ * @param {boolean} opt_isFlyoutBlock Whether the block is in the flyout.
  */
 Blocks.prototype.createBlock = function (block, opt_isFlyoutBlock) {
     // Create new block

src/engine/runtime.js

@@ -10,7 +10,7 @@ var defaultBlockPackages = {
 
 /**
  * Manages blocks, stacks, and the sequencer.
- * @param blocks Blocks instance for this runtime.
+ * @param {!Blocks} blocks Blocks instance for this runtime.
  */
 function Runtime (blocks) {
     // Bind event emitter

src/engine/sequencer.js

@@ -32,6 +32,7 @@ Sequencer.DEBUG_BLOCK_CALLS = true;
 
 /**
  * Step through all threads in `this.threads`, running them in order.
+ * @param {Array.<Thread>} threads List of which threads to step.
  * @return {Array.<Thread>} All threads which have finished in this iteration.
  */
 Sequencer.prototype.stepThreads = function (threads) {
@@ -147,6 +148,9 @@ Sequencer.prototype.stepThread = function (thread) {
     /**
      * A callback for the primitive to start hats.
      * @todo very hacked...
+     * Provide a callback that is passed in a block and returns true
+     * if it is a hat that should be triggered.
+     * @param {Function} callback Provided callback.
      */
     var startHats = function(callback) {
         var stacks = instance.runtime.blocks.getStacks();