Add a pass of jsdocs

lib/base_client.js

@@ -11,10 +11,25 @@
 
 const Mixins = require('./mixins.json');
 
-module.exports = class ThingpediaClientBase {
+/**
+ * The base class of all clients to access the Thingpedia API.
+ *
+ * Accessing the Thingpedia API from Almond occurs in a platform-specific manner,
+ * through clients that extend this class.
+ */
+class BaseClient {
+    /**
+     * @protected
+     */
     constructor() {
     }
 
+    /**
+     * The locale to use when querying Thingpedia, as BCP 47 tag.
+     *
+     * @type {string}
+     * @readonly
+     */
     get locale() {
         throw new Error('not implemented');
     }
@@ -100,4 +115,5 @@ module.exports = class ThingpediaClientBase {
             mixins[mixin.kind] = mixin;
         return Promise.resolve(mixins);
     }
-};
+}
+module.exports = BaseClient;

lib/base_device.js

@@ -55,22 +55,38 @@ class BaseDevice extends events.EventEmitter {
      *
      * @param {BaseEngine} engine - the shared Almond engine initializing this device
      * @param {Object} state - arbitrary JSON data associated with this device
+     * @protected
      */
     constructor(engine, state) {
         super();
         this._engine = engine;
-        this.state = state;
 
-        // Set this to a device specific ID plus something unique
-        // (eg "mydevice-aa-bb-cc-dd-ee-ff") so that no other device
-        // can possibly have the same ID
-        // If you leave it unset, DeviceDatabase will pick for you
+        /**
+         * The current device state.
+         *
+         * @readonly
+         * @type {Object}
+         */
+        this.state = state;
 
         // provide default uniqueId for config.none() devices
         const ast = this.metadata;
         const params = Object.keys(ast.params);
         const isNoneFactory = ast.auth.type === 'none' && params.length === 0;
         const isNoneAuth = ast.auth.type === 'none';
+
+        /**
+         * The unique ID of this device instance.
+         *
+         * Device implementations should set this the Thingpedia kind (class ID) plus something unique
+         * (eg "com.mydevice/aa-bb-cc-dd-ee-ff") so that no other device
+         * can possibly have the same ID.
+         * If you leave it unset, a unique identifier will be automatically generated.
+         *
+         * @name BaseDevice#uniqueId
+         * @type {string}
+         * @member
+         */
         if (isNoneFactory)
             this.uniqueId = this.kind;
         else if (isNoneAuth)
@@ -81,17 +97,49 @@ class BaseDevice extends events.EventEmitter {
         // provide default name and description
         // NOTE: these are not getters, because the subclass can override
         // them and mutate them as it wishes
+
+        /**
+         * The user-visible name of this device instance.
+         *
+         * If multiple instances of the same class can reasonably be configured by the same
+         * user (e.g. multiple devices of the same brand, or multiple accounts on the same service),
+         * they should have different names.
+         * This defaults to the name provided in Thingpedia.
+         *
+         * @type {string}
+         */
         this.name = ast.name;
+        /**
+         * A longer description of this device instance.
+         *
+         * This can be used to add additional distinguishing information, such as the URL
+         * or address of a local gateway.
+         * It defaults to the description provided in Thingpedia.
+         *
+         * @type {string}
+         */
         this.description = ast.description;
 
-        // Set these to protocol/discovery specific IDs (such as
-        // "bluetooth/aa-bb-cc-dd-ee-ff") so that it is unlikely that
-        // another device has the same ID
+        /**
+         * Discovery protocol descriptors.
+         *
+         * Device implementations should set these to protocol/discovery specific IDs (such as
+         * "bluetooth/aa-bb-cc-dd-ee-ff") so that it is unlikely that
+         * another device has the same ID.
+         *
+         * @type {string[]}
+         */
         this.descriptors = [];
 
-        // Set to true if this device should not be stored in the devicedb
-        // but only kept in memory (ie, its lifetime is managed by some
-        // device discovery module, or it's a subdevice of some other device)
+        /**
+         * Indicates a transient device.
+         *
+         * Set to true if this device should not be stored in the device database
+         * but only kept in memory (i.e., its lifetime is managed by some
+         * device discovery module, or it's a subdevice of some other device).
+         *
+         * @type {boolean}
+         */
         this.isTransient = false;
 
         this._ownerTier = undefined;
@@ -256,6 +304,9 @@ class BaseDevice extends events.EventEmitter {
 
     /**
      * The Thingpedia "kind" (unique class ID) of this device.
+     *
+     * @type string
+     * @readonly
      */
     get kind() {
         return this.state.kind;
@@ -269,7 +320,8 @@ class BaseDevice extends events.EventEmitter {
     /**
      * Access the current platform for this device instance.
      *
-     * @return {BasePlatform}
+     * @type {BasePlatform}
+     * @readonly
      */
     get platform() {
         return this._engine.platform;
@@ -278,7 +330,8 @@ class BaseDevice extends events.EventEmitter {
     /**
      * Access the current engine for this device instance.
      *
-     * @return {BaseEngine}
+     * @type {BaseEngine}
+     * @readonly
      * @deprecated It is recommended to avoid using the {@link BaseEngine} API as it can change without notice.
      */
     get engine() {
@@ -293,6 +346,7 @@ class BaseDevice extends events.EventEmitter {
      * persisted on disk.
      *
      * @fires BaseDevice#state-changed
+     * @protected
      */
     stateChanged() {
         /**

lib/base_engine.js

@@ -13,7 +13,22 @@ const ThingTalk = require('thingtalk');
 
 const ThingpediaHttpClient = require('./http_client');
 
-module.exports = class BaseEngine {
+/**
+ * The base Almond engine class.
+ *
+ * This contains the only API that should be considered stable in the Engine.
+ * All other APIs are a private implementation detail.
+ */
+class BaseEngine {
+    /**
+     * Construct an engine instance.
+     *
+     * @param {BasePlatform} platform - the platform associated with this engine
+     * @param {Object} options - additional options
+     * @param {string} [options.thingpediaUrl] - the Thingpedia URL to use (if the platform
+     *                                           does not provide a {@link BaseClient})
+     * @protected
+     */
     constructor(platform, options = {}) {
         this._platform = platform;
 
@@ -25,16 +40,46 @@ module.exports = class BaseEngine {
         this._schemas = new ThingTalk.SchemaRetriever(this._thingpedia);
     }
 
+    /**
+     * The current tier of the engine.
+     *
+     * See {@link BaseDevice.Tier} for an explanation.
+     *
+     * @type {BaseDevice.Tier}
+     * @readonly
+     */
     get ownTier() {
         return 'desktop';
     }
+
+    /**
+     * The platform associated with the engine.
+     *
+     * @type {BasePlatform}
+     * @readonly
+     */
     get platform() {
         return this._platform;
     }
+
+    /**
+     * The Thingpedia Client associated with the engine.
+     *
+     * @type {BaseClient}
+     * @readonly
+     */
     get thingpedia() {
         return this._thingpedia;
     }
+
+    /**
+     * The ThingTalk SchemaRetriever associated with the engine.
+     *
+     * @type {ThingTalk.SchemaRetriever}
+     * @readonly
+     */
     get schemas() {
         return this._schemas;
     }
-};
+}
+module.exports = BaseEngine;