Merge pull request #41 from stanford-oval/wip/jsdoc

Document the Thingpedia SDK with jsdoc

index.js

@@ -26,22 +26,59 @@ const BasePlatform = require('./lib/base_platform');
 
 const ThingTalk = require('thingtalk');
 
+/**
+ * Versioning information for the library.
+ *
+ * Use this object to check if the currently loaded Thingpedia SDK
+ * is compatible with your device, and to dynamically check if a specific
+ * feature is present.
+ *
+ * Note: you should never bundle the Thingpedia SDK with your device.
+ *
+ * @alias version
+ * @namespace
+ */
 const VERSION = {
+    /** Major version number (incremented on incompatible changes) */
     major: 2,
+    /** Minor version number (incremented on feature additions) */
     minor: 6,
+    /** Full version string, in semantic version format */
     full: '2.6.0-alpha.1',
+    /** Convert the version number to a number (for comparisons) */
     valueOf() {
         return this.major * 100 + this.minor;
     },
     toString() {
         return this.full;
     },
+    /**
+     * Check if the current version is compatible with the passed in version
+     *
+     * @param {number|Version} v - the version, as a number or object with `major`
+     *                             and minor properties
+     * @return {Boolean}
+     */
     compatible(v) {
         if (typeof v === 'number')
             return this.valueOf() >= v && Math.floor(v/100) === this.major;
         else
             return this.major === v.major && this.minor >= v.minor;
     },
+    /**
+     * Check if the given feature is present.
+     *
+     * It is ok to pass invalid or unrecognized feature names to this function,
+     * which will then return `false`.
+     *
+     * In this version of the library, the following feature names are recognized:
+     * - `rss`: RSS helpers and loaders
+     * - `value-types`: ThingTalk value types are re-exported
+     * - `thingpedia-client`: Thingpedia Client APIs are present
+     *
+     * @param {String} f - a feature name
+     * @return {Boolean} whether the named feature is supported.
+     */
     hasFeature(f) {
         switch (f) {
         case 'rss':

jsdoc.json

@@ -0,0 +1,23 @@
+{
+    "plugins": [
+        "plugins/markdown"
+    ],
+    "recurseDepth": 10,
+    "source": {
+        "includePattern": ".+\\.js(doc|x)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "templates": {
+        "cleverLinks": true,
+        "monospaceLinks": true,
+        "default": {
+          "useLongnameInNav": true
+        }
+    }
+}
+

lib/base_client.js

@@ -11,10 +11,27 @@
 
 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.
+ *
+ * @interface
+ */
+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 +117,5 @@ module.exports = class ThingpediaClientBase {
             mixins[mixin.kind] = mixin;
         return Promise.resolve(mixins);
     }
-};
+}
+module.exports = BaseClient;