boatload of API docs

.eslintrc.yml

@@ -1,9 +1,16 @@
 extends:
-  - semistandard
-  - plugin:lodash-fp/recommended
+- semistandard
+- plugin:lodash-fp/recommended
 plugins:
-  - lodash-fp
+- lodash-fp
 rules:
   strict:
-    - error
-    - safe
+  - error
+  - safe
+  valid-jsdoc: error
+  require-jsdoc:
+  - error
+  - require:
+      FunctionDeclaration: true
+      MethodDefinition: true
+      ClassDeclaration: true

.gitignore

@@ -21,3 +21,4 @@ jspm_packages
 .yarn-integrity
 dist/
 minimal/
+doc/

esdoc.json

@@ -0,0 +1,26 @@
+{
+  "source": "./src",
+  "destination": "./doc",
+  "experimentalProposal": {
+    "classProperties": true,
+    "objectRestSpread": true,
+    "decorators": true,
+    "doExpressions": true,
+    "functionBind": true,
+    "asyncGenerators": true,
+    "exportExtensions": true,
+    "dynamicImport": true
+  },
+  "coverage": false,
+  "test": {
+    "type": "mocha",
+    "source": "./test/unit",
+    "includes": ["\\.spec\\.js$"]
+  },
+  "plugins": [
+    {
+      "name": "esdoc-node"
+    }
+  ],
+  "unexportIdentifier": true
+}

package.json

@@ -38,9 +38,10 @@
     "build:watch": "concurrently \"babel --watch --source-maps --out-dir dist src\" \"cross-env BABEL_ENV=production webpack --watch\"",
     "prepublish": "npm run build",
     "pretest": "eslint '*.js' test src",
-    "test": "nyc --require babel-register mocha --require test/harness.js 'test/unit/*.spec.js'",
+    "test": "nyc -a --include src --require babel-register mocha --require test/harness.js 'test/unit/*.spec.js'",
     "test:e2e": "mocha --require babel-register --require test/harness.js 'test/e2e/**/*.spec.js'",
-    "preversion": "npm test"
+    "preversion": "npm test",
+    "docs": "esdoc"
   },
   "devDependencies": {
     "babel-cli": "^6.24.0",
@@ -53,6 +54,8 @@
     "babili-webpack-plugin": "^0.0.11",
     "concurrently": "^3.4.0",
     "cross-env": "^3.2.3",
+    "esdoc": "^0.5.2",
+    "esdoc-node": "^1.0.1",
     "eslint": "^3.17.1",
     "eslint-config-semistandard": "^8.0.0",
     "eslint-config-standard": "^7.0.1",

src/codes.js

@@ -1,38 +1,54 @@
 import _ from 'lodash/fp';
 
-const executionCodes = {
-  0x00: 'invalidInstruction',
-  0x01: 'success',
-  0x02: 'invalidComponentID',
-  0x03: 'invalidPageID',
-  0x04: 'invalidPictureID',
-  0x05: 'invalidFontID',
-  0x11: 'invalidBaudRate',
-  0x12: 'invalidCurveControl',
-  0x1a: 'invalidVariableName',
-  0x1b: 'invalidVariableOperation',
-  0x1c: 'assignmentFailure',
-  0x1d: 'eepromFailure',
-  0x1e: 'invalidParameterQuantity',
-  0x1f: 'ioOperationFailure',
-  0x20: 'undefinedEscapeCharacter',
-  0x23: 'variableNameTooLong'
+/**
+ * Maps of instruction codes, namespaced by type.
+ * @private
+ */
+const codes = {
+  responseCodes: {
+    0x00: 'invalidInstruction',
+    0x01: 'success',
+    0x02: 'invalidComponentID',
+    0x03: 'invalidPageID',
+    0x04: 'invalidPictureID',
+    0x05: 'invalidFontID',
+    0x11: 'invalidBaudRate',
+    0x12: 'invalidCurveControl',
+    0x1a: 'invalidVariableName',
+    0x1b: 'invalidVariableOperation',
+    0x1c: 'assignmentFailure',
+    0x1d: 'eepromFailure',
+    0x1e: 'invalidParameterQuantity',
+    0x1f: 'ioOperationFailure',
+    0x20: 'undefinedEscapeCharacter',
+    0x23: 'variableNameTooLong'
+  },
+  eventCodes: {
+    0x65: 'touchEvent',
+    0x66: 'pageId',
+    0x67: 'touchCoordinate',
+    0x68: 'touchCoordinateOnWake',
+    0x70: 'stringData',
+    0x71: 'numericData',
+    0x86: 'autoSleep',
+    0x87: 'autoWake',
+    0x88: 'startup',
+    0x89: 'cardUpgrade',
+    0xfd: 'transmitFinished',
+    0xfe: 'transmitReady'
+  }
 };
 
-const eventCodes = {
-  0x65: 'touchEvent',
-  0x66: 'pageId',
-  0x67: 'touchCoordinate',
-  0x68: 'touchCoordinateOnWake',
-  0x70: 'stringData',
-  0x71: 'numericData',
-  0x86: 'autoSleep',
-  0x87: 'autoWake',
-  0x88: 'startup',
-  0x89: 'cardUpgrade',
-  0xfd: 'transmitFinished',
-  0xfe: 'transmitReady'
-};
+/**
+ * Map of "event" instruction codes
+ * @private
+ * @type {Map}
+ */
+export const eventCodeMap = new Map(_.toPairs(codes.eventCodes));
 
-export const eventCodeMap = new Map(_.toPairs(eventCodes));
-export const responseCodeMap = new Map(_.toPairs(executionCodes));
+/**
+ * Map of "response" instruction codes
+ * @private
+ * @type {Map}
+ */
+export const responseCodeMap = new Map(_.toPairs(codes.responseCodes));

src/index.js

@@ -2,6 +2,38 @@ import {Nextion} from './nextion';
 import {NextionProtocol} from './protocol';
 import {UART} from './uart';
 
+/**
+ * @external {EventEmitter} https://nodejs.org/api/events.html#events_class_eventemitter
+ */
+
+/**
+ * @external {Duplex} https://nodejs.org/api/stream.html#stream_class_stream_duplex
+ */
+
+/**
+ * @external {Serialport} https://npmjs.com/package/serialport
+ */
+
+/**
+ * @external {Buffer} https://nodejs.org/api/buffer.html#buffer_class_buffer
+ */
+
+/**
+ * Valid options to supply a {@link Nextion} or {@link UART} constructor.
+ * All options are optional.
+ * @typedef {Object} NextionOptions
+ * @property {string} [port] - Name (e.g. "COM3") or path (e.g. "/dev/ttyUSB0")
+ * @property {number} [baudRate=9600] - Baud rate of Nextion device.
+ */
+
+/**
+ * Instantiates a Nextion instance and fulfills a Promise
+ * when it's listening for data.
+ * @param {UART} uart - UART instance
+ * @param {NextionOptions} [opts] - Extra options
+ * @private
+ * @returns {Promise<Nextion>} New Nextion instance
+ */
 function instantiate (uart, opts) {
   return new Promise(resolve => {
     const nextion = new Nextion(uart, opts, () => {
@@ -10,12 +42,31 @@ function instantiate (uart, opts) {
   });
 }
 
-Nextion.from = Nextion.create = (port, opts) => UART.from(port, opts)
+/**
+ * Create a Nextion instance.
+ * @param {string|Object} [port] - Name of port (`COM1`, `/dev/tty.usbserial`, etc.), `Serialport` instance or `Duplex` stream.  Omit for autodetection.
+ * @param {NextionOptions} [opts] - Options
+ * @returns {Promise<Nextion>} - Nextion instance
+ */
+Nextion.from = (port, opts) => UART.from(port, opts)
   .then(instantiate);
+Nextion.create = Nextion.from;
 
+/**
+ * Create a Nextion instance using an existing connected `Serialport` instance or `Duplex` stream.
+ * @param {string} serialPort - `Serialport` instance, `Duplex` stream, etc.
+ * @param {NextionOptions} [opts] - Options
+ * @returns {Promise<Nextion>} - Nextion instance
+ */
 Nextion.fromSerial = (serialPort, opts) => UART.fromSerial(serialPort, opts)
   .then(instantiate);
 
+/**
+ * Create a Nextion instance, optionally specifying a port name.
+ * @param {string} [portName] - Name of port (`COM1`, `/dev/tty.usbserial`, etc.).  Omit for autodetection.
+ * @param {NextionOptions} [opts] - Options
+ * @returns {Promise<Nextion>} - Nextion instance
+ */
 Nextion.fromPort = (portName, opts) => UART.fromPort(portName, opts)
   .then(instantiate);
 

src/nextion.js

@@ -3,24 +3,40 @@ import {System} from './system';
 import debug_ from 'debug';
 import _ from 'lodash/fp';
 
+/**
+ * @ignore
+ */
 const debug = debug_('nextion:Nextion');
 
+/**
+ * Applies defaults to an object
+ * @param {NextionOptions} obj - Defaults are applied to this object
+ * @returns {NextionOptions} Options w/ defaults applied
+ * @function
+ * @private
+ */
 const applyDefaults = _.defaults({
   // XXX: does nothing yet
   enhanced: true
 });
 
+/**
+ * High-level abstraction for interacting with a Nextion device.
+ * @extends {EventEmitter}
+ */
 export class Nextion extends EventEmitter {
   /**
-   *
-   * @param {UART} uart - UART instance (serial port wrapper)
+   * Begins listening for data via a {@link UART} instance.
+   * @param {UART} uart - {@link UART} instance
    * @param {Object|Function} [opts] - Options or `connectListener`
    * @param {Function} [connectListener] - Callback to run when listening for
    *   Nextion data
+   * @emits {error} When binding via `uart` fails
+   * @throws {ReferenceError} When `uart` is missing
    */
   constructor (uart, opts = {}, connectListener = _.noop) {
     if (!uart) {
-      throw new Error(
+      throw new ReferenceError(
         'Invalid parameters; Use Nextion.from(), Nextion.fromSerial(), or Nextion.fromPort()');
     }
 
@@ -36,7 +52,18 @@ export class Nextion extends EventEmitter {
       connectListener();
     });
 
+    /**
+     * Options
+     * @type {Object}
+     * @private
+     */
     this.opts = applyDefaults(opts);
+
+    /**
+     * Internal UART instance
+     * @type {UART}
+     * @private
+     */
     this.uart = uart;
 
     // when a Nextion event occurs, re-emit it with event name
@@ -55,25 +82,39 @@ export class Nextion extends EventEmitter {
         this.emit('error', err);
       });
 
+    /**
+     * System-level Nextion commands
+     * @type {System}
+     */
     this.system = new System(uart);
 
     debug('Instantiated');
   }
 
   /**
-   * Sets a variable on the current page to a value
+   * Sets a local or global variable on the current page to a value
    * @param {string} name - Name of variable
-   * @param {*} [value] - Value to set variable to
-   * @returns {Promise.<*>}
+   * @param {*} [value] - New variable value
+   * @returns {Promise<ResponseResult>} Result
    */
   setValue (name, value) {
     return this.uart.setValue(name, value);
   }
 
-  setComponentValue (componentName, value) {
-    return this.setVariableValue(`${componentName}.val`, value);
+  /**
+   * Sets a the value of a local component
+   * @param {string} name - Name of component
+   * @param {*} [value] - New component value
+   * @returns {Promise<ResponseResult>} Result
+   */
+  setComponentValue (name, value) {
+    return this.setVariableValue(`${name}.val`, value);
   }
 
+  /**
+   * Closes connection to Nextion device.
+   * @returns {Promise<Nextion>} This instance
+   */
   close () {
     return this.uart.unbind()
       .then(() => {