JSDoc all the things

.eslintrc

@@ -9,6 +9,19 @@
   },
   "rules" : {
     "new-cap": [0],
-    "max-params": [1]
+    "max-params": [1],
+    "require-jsdoc": [2, {
+      "require": {
+        "FunctionDeclaration": true,
+        "MethodDefinition": true,
+        "ClassDeclaration": false
+      }
+    }],
+    "valid-jsdoc": [2, {
+      "requireParamDescription": false,
+      "requireReturnDescription": false,
+      "requireReturnType": true
+    }]
   }
 }
+

index.js

@@ -2,6 +2,10 @@
 
 var configPageHtml = require('./tmp/config-page.html');
 
+/**
+ * @param {string} input
+ * @returns {string}
+ */
 function encodeDataUri(input) {
   if (window.btoa) {
     return 'data:text/html;base64,' + encodeURIComponent(window.btoa(input));
@@ -65,6 +69,7 @@ function Clay(config, customFn) {
 /**
  * Generate the Data URI used by the config Page with settings injected
  * @param {string} returnTo - used while developing on desktop.
+ * @return {string}
  */
 Clay.prototype.generateUrl = function(returnTo) {
   var settings;
@@ -91,6 +96,11 @@ Clay.prototype.generateUrl = function(returnTo) {
   );
 };
 
+/**
+ * Parse the response from the webviewclosed event data
+ * @param {string} response
+ * @returns {{}}
+ */
 Clay.prototype.getSettings = function(response) {
   // Decode and parse config data as JSON
   var settings = JSON.parse(decodeURIComponent(response));

src/scripts/config-page.js

@@ -15,14 +15,14 @@ var clayConfig = new ClayConfig(settings, config, $mainForm);
 clayConfig.on(clayConfig.EVENTS.BEFORE_BUILD, function() {
 
   // register components here
-  this.registerComponent(require('pebble-clay-components/dist/components/heading'));
-  this.registerComponent(require('pebble-clay-components/dist/components/text'));
-  this.registerComponent(require('pebble-clay-components/dist/components/footer'));
-  this.registerComponent(require('pebble-clay-components/dist/components/input'));
-  this.registerComponent(require('pebble-clay-components/dist/components/color'));
-  this.registerComponent(require('pebble-clay-components/dist/components/select'));
-  this.registerComponent(require('pebble-clay-components/dist/components/toggle'));
-  this.registerComponent(require('pebble-clay-components/dist/components/submit'));
+  this.registerComponent(require('pebble-clay-components').heading);
+  this.registerComponent(require('pebble-clay-components').text);
+  this.registerComponent(require('pebble-clay-components').footer);
+  this.registerComponent(require('pebble-clay-components').input);
+  this.registerComponent(require('pebble-clay-components').color);
+  this.registerComponent(require('pebble-clay-components').select);
+  this.registerComponent(require('pebble-clay-components').toggle);
+  this.registerComponent(require('pebble-clay-components').submit);
 });
 
 clayConfig.on(clayConfig.EVENTS.AFTER_BUILD, function() {

src/scripts/lib/clay-config.js

@@ -23,9 +23,9 @@ var manipulators = require('./manipulators');
 
 /**
  * @extends ClayEvents
- * @param settings
- * @param config
- * @param $rootContainer
+ * @param {{}} settings - setting that were set from a previous session
+ * @param {[]|{}} config
+ * @param {M} $rootContainer
  * @constructor
  */
 function ClayConfig(settings, config, $rootContainer) {
@@ -39,10 +39,11 @@ function ClayConfig(settings, config, $rootContainer) {
 
   /**
    * Add item(s) to the config
-   * @param {Clay~ConfigItem|array} items
-   * @param {M} [$container]
+   * @param {Clay~ConfigItem|array} item
+   * @param {M} $container
+   * @return {void}
    */
-  var _addItems = function(item, $container) {
+  function _addItems(item, $container) {
     if (Array.isArray(item)) {
       item.forEach(function(item) {
         _addItems(item, $container);
@@ -73,14 +74,15 @@ function ClayConfig(settings, config, $rootContainer) {
 
       $container.add(clayItem.$element);
     }
-  };
+  }
 
   /**
-   *
+   * Throws if the config has not been built yet.
    * @param {string} fnName
+   * @returns {boolean}
    * @private
    */
-  var _checkBuilt = function(fnName) {
+  function _checkBuilt(fnName) {
     if (!_isBuilt) {
       throw new Error(
         'ClayConfig not built. build() must be run before ' +
@@ -88,7 +90,7 @@ function ClayConfig(settings, config, $rootContainer) {
       );
     }
     return true;
-  };
+  }
 
   self.EVENTS = {
     /**
@@ -134,8 +136,8 @@ function ClayConfig(settings, config, $rootContainer) {
   };
 
   /**
-   * @param {string} key
-   * @returns {[ClayItem]}
+   * @param {string} type
+   * @returns {Array.<ClayItem>}
    */
   self.getItemsByType = function(type) {
     _checkBuilt('getItemsByType');
@@ -188,6 +190,7 @@ function ClayConfig(settings, config, $rootContainer) {
  * @param {function} component.manipulator.get - get manipulator method
  * @param {{}} component.defaults - template defaults
  * @param {function} [component.initialize] - method to scaffold the component
+ * @return {void}
  */
 ClayConfig.registerComponent = function(component) {
   var _component = _.copyObj(component);

src/scripts/lib/clay-events.js

@@ -2,6 +2,7 @@
 
 var $ = require('../vendor/minified/minified').$;
 var _ = require('../vendor/minified/minified')._;
+
 /**
  * Attaches event methods to the context.
  * Call with ClayEvents.call(yourObject, $eventTarget)
@@ -19,13 +20,19 @@ function ClayEvents($eventTarget) {
    * @returns {string}
    * @private
    */
-  var _transformEventNames = function(events) {
+  function _transformEventNames(events) {
     return events.split(' ').map(function(event) {
       return '|' + event.replace(/^\|/, '');
     }).join(' ');
-  };
+  }
 
-  var _registerEventProxy = function(handler, proxy) {
+  /**
+   * @param {function} handler
+   * @param {function} proxy
+   * @returns {function}
+   * @private
+   */
+  function _registerEventProxy(handler, proxy) {
     var eventProxy = _.find(_eventProxies, function(item) {
       return item.handler === handler ? item : null;
     });
@@ -35,13 +42,18 @@ function ClayEvents($eventTarget) {
       _eventProxies.push(eventProxy);
     }
     return eventProxy.proxy;
-  };
+  }
 
-  var _getEventProxy = function(handler) {
+  /**
+   * @param {function} handler
+   * @returns {function}
+   * @private
+   */
+  function _getEventProxy(handler) {
     return _.find(_eventProxies, function(item) {
       return item.handler === handler ? item.proxy : null;
     });
-  };
+  }
 
   /**
    * Attach an event listener to the item.
@@ -60,8 +72,8 @@ function ClayEvents($eventTarget) {
   };
 
   /**
-   * Remove the given event handler.
-   * @see {@link http://minifiedjs.com/api/off.html|$.off()}
+   * Remove the given event handler. NOTE: This will remove the handler from all
+   * registered events
    * @param {function} handler
    * @returns {ClayEvents}
    */
@@ -74,11 +86,10 @@ function ClayEvents($eventTarget) {
   };
 
   /**
-   * Trigger an event. This proxies minified.js' trigger.
+   * Trigger an event.
    * @param {string} name - a single event name to trigger
    * @param {object} [eventObj] - an object to pass to the event handler,
    * provided the handler does not have custom arguments.
-   * @see {@link http://minifiedjs.com/api/trigger.html|.trigger()}
    * @returns {ClayEvents}
    */
   self.trigger = function(name, eventObj) {

src/scripts/lib/clay-item.js

@@ -8,7 +8,7 @@ var ClayEvents = require('./clay-events');
 
 /**
  * @extends ClayEvents
- * @param config
+ * @param {Clay~ConfigItem} config
  * @constructor
  */
 function ClayItem(config) {

src/scripts/lib/utils.js

@@ -10,6 +10,7 @@
  * @param {boolean} [descriptor.writable]
  * @param {function} [descriptor.get]
  * @param {function} [descriptor.set]
+ * @return {void}
  */
 module.exports.updateProperties = function(obj, descriptor) {
   Object.getOwnPropertyNames(obj).forEach(function(prop) {

test/fixture.js

@@ -7,14 +7,12 @@ var ClayItem = require('../src/scripts/lib/clay-item');
 var ClayConfig = require('../src/scripts/lib/clay-config');
 var idCounter = 0;
 
-var componentRegistry = require('../src/scripts/lib/component-registry');
-
 // add some components to the registry to test
-ClayConfig.registerComponent(require('pebble-clay-components/dist/components/text'));
-ClayConfig.registerComponent(require('pebble-clay-components/dist/components/input'));
-ClayConfig.registerComponent(require('pebble-clay-components/dist/components/toggle'));
-ClayConfig.registerComponent(require('pebble-clay-components/dist/components/footer'));
-ClayConfig.registerComponent(require('pebble-clay-components/dist/components/select'));
+ClayConfig.registerComponent(require('pebble-clay-components').text);
+ClayConfig.registerComponent(require('pebble-clay-components').input);
+ClayConfig.registerComponent(require('pebble-clay-components').toggle);
+ClayConfig.registerComponent(require('pebble-clay-components').footer);
+ClayConfig.registerComponent(require('pebble-clay-components').select);
 
 /**
  * @param {string|{}} config

test/spec/lib/clay-config.js

@@ -2,7 +2,7 @@
 
 var assert = require('chai').assert;
 var _ = require('../../../src/scripts/vendor/minified/minified')._;
-var textComponent = require('pebble-clay-components/dist/components/text');
+var textComponent = require('pebble-clay-components').text;
 var componentRegistry = require('../../../src/scripts/lib/component-registry');
 var checkReadOnly = require('../../test-utils').checkReadOnly;
 var fixtures = require('../../fixture');

test/spec/lib/clay-events.js

@@ -12,10 +12,14 @@ var ctx;
 
 var eventCounter = 0;
 
-var createEventName = function() {
+/**
+ * Create a unique event name
+ * @returns {string}
+ */
+function createEventName() {
   eventCounter++;
   return 'test-event-' + eventCounter;
-};
+}
 
 describe('ClayEvents', function() {
 

test/test-utils.js

@@ -5,6 +5,7 @@ var assert = require('chai').assert;
 /**
  * @param {Object} object
  * @param {Array} properties
+ * @return {void}
  */
 module.exports.checkReadOnly = function(object, properties) {
   properties.forEach(function(property) {