Better documentation

codetheweb · Jan 12, 2018 · 96337f3 · 96337f3
1 parent 5687892
commit 96337f3
Show file tree

Hide file tree

Showing 3 changed files with 103 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -36,18 +36,18 @@ This should report the current status, set the device to the opposite of what it
 
 See the [setup instructions](docs/SETUP.md) for how to find the needed parameters.
 
-## Docs
+## 📓 Docs
 
 See the [docs](docs/API.md).
+
 **IMPORTANT**: Only one TCP connection can be in use with a device at once. If testing this, do not have the app on your phone open.
 
 ## TODO
 
 3.  Better documentation.
-4.  Support arbitrary control schemes for devices as self-reported.
-5.  Use Promises for all functions?
 7.  Add automated tests
 8.  Document details of protocol
+9.  Add error message for no IP
 
 ## Contributors
 

diff --git a/docs/API.md b/docs/API.md
@@ -8,7 +8,6 @@ Docs
     -   [resolveIds](#resolveids)
     -   [get](#get)
     -   [set](#set)
-    -   [\_extractJSON](#_extractjson)
 
 ## TuyaDevice
 
@@ -17,13 +16,25 @@ Represents a Tuya device.
 **Parameters**
 
 -   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options for constructing a TuyaDevice
-    -   `options.type` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type of device (optional, default `'outlet'`)
-    -   `options.ip` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** IP of device
-    -   `options.port` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** port of device (optional, default `6668`)
-    -   `options.id` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** ID of device
-    -   `options.uid` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** UID of device (optional, default `''`)
-    -   `options.key` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** encryption key of device
-    -   `options.version` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** protocol version (optional, default `3.1`)
+    -   `options.type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type of device (optional, default `'outlet'`)
+    -   `options.ip` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** IP of device
+    -   `options.port` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** port of device (optional, default `6668`)
+    -   `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** ID of device
+    -   `options.uid` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** UID of device (optional, default `''`)
+    -   `options.key` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** encryption key of device
+    -   `options.version` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** protocol version (optional, default `3.1`)
+
+**Examples**
+
+```javascript
+const tuya = new TuyaDevice({id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'})
+```
+
+```javascript
+const tuya = new TuyaDevice([
+{id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'},
+{id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}])
+```
 
 ### resolveIds
 
@@ -33,32 +44,55 @@ Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
 
 ### get
 
-Gets the device's current status. Defaults to returning only the first 'dps', but by setting {schema: true} you can get everything.
+Gets the device's current status. Defaults to returning only the value of the first result,
+but by setting {schema: true} you can get everything.
 
 **Parameters**
 
--   `options`  
--   `ID` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** optional, ID of device. Defaults to first device.
--   `callback` **function ([error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error), result)** 
+-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** optional options for getting data
+    -   `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** ID of device
+    -   `options.schema` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** true to return entire schema, not just the first result
+
+**Examples**
+
+```javascript
+// get status for device with one property
+tuya.get().then(status => console.log(status))
+```
+
+```javascript
+// get status for specific device with one property
+tuya.get({id: 'xxxxxxxxxxxxxxxxxxxx'}).then(status => console.log(status))
+```
+
+```javascript
+// get all available data from device
+tuya.get({schema: true}).then(data => console.log(data))
+```
+
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** returns boolean if no options are provided, otherwise returns object of results
 
 ### set
 
 Sets the device's status.
 
 **Parameters**
 
--   `options`  
--   `on` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` for on, `false` for off
-    {id, set: true|false, dps:1}
--   `callback` **function ([error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error), result)** returns `true` if the command succeeded
-
-### \_extractJSON
+-   `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** options for setting properties
+    -   `options.id` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)?** ID of device
+    -   `options.set` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** `true` for on, `false` for off
+    -   `options.dps` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** dps index to change
 
-Extracts JSON from a raw buffer and returns it as an object.
+**Examples**
 
-**Parameters**
+```javascript
+// set default property on default device
+tuya.set({set: true}).then(() => console.log('device was changed'))
+```
 
--   `data`  
--   `buffer` **[Buffer](https://nodejs.org/api/buffer.html)** of data
+```javascript
+// set custom property on non-default device
+tuya.set({id: 'xxxxxxxxxxxxxxxxxxxx', 'dps': 2, set: true}).then(() => console.log('device was changed'))
+```
 
-Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** extracted object
+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)>** returns `true` if the command succeeded
diff --git a/index.js b/index.js
@@ -11,15 +11,21 @@ const requests = require('./requests.json');
 
 /**
 * Represents a Tuya device.
-* @constructor
+* @class
 * @param {Object} options - options for constructing a TuyaDevice
-* @param {string} [options.type='outlet'] - type of device
-* @param {string} options.ip - IP of device
-* @param {number} [options.port=6668] - port of device
-* @param {string} options.id - ID of device
-* @param {string} [options.uid=''] - UID of device
-* @param {string} options.key - encryption key of device
-* @param {number} [options.version=3.1] - protocol version
+* @param {String} [options.type='outlet'] - type of device
+* @param {String} [options.ip] - IP of device
+* @param {Number} [options.port=6668] - port of device
+* @param {String} options.id - ID of device
+* @param {String} [options.uid=''] - UID of device
+* @param {String} options.key - encryption key of device
+* @param {Number} [options.version=3.1] - protocol version
+* @example
+* const tuya = new TuyaDevice({id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'})
+* @example
+* const tuya = new TuyaDevice([
+* {id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'},
+* {id: 'xxxxxxxxxxxxxxxxxxxx', key: 'xxxxxxxxxxxxxxxx'}])
 */
 function TuyaDevice(options) {
   this.devices = [];
@@ -51,7 +57,8 @@ function TuyaDevice(options) {
 }
 
 /**
-* Resolves IDs stored in class to IPs.
+* Resolves IDs stored in class to IPs. If you didn't pass IPs to the constructor,
+* you must call this before doing anything else.
 * @returns {Promise<Boolean>} - true if IPs were found and devices are ready to be used
 */
 TuyaDevice.prototype.resolveIds = function () {
@@ -96,9 +103,21 @@ TuyaDevice.prototype.resolveIds = function () {
 };
 
 /**
-* Gets the device's current status. Defaults to returning only the first 'dps', but by setting {schema: true} you can get everything.
-* @param {string} ID - optional, ID of device. Defaults to first device.
-* @param {function(error, result)} callback
+* Gets the device's current status. Defaults to returning only the value of the first result,
+* but by setting {schema: true} you can get everything.
+* @param {Object} [options] - optional options for getting data
+* @param {String} [options.id] - ID of device
+* @param {Boolean} [options.schema] - true to return entire schema, not just the first result
+* @example
+* // get status for device with one property
+* tuya.get().then(status => console.log(status))
+* @example
+* // get status for specific device with one property
+* tuya.get({id: 'xxxxxxxxxxxxxxxxxxxx'}).then(status => console.log(status))
+* @example
+* // get all available data from device
+* tuya.get({schema: true}).then(data => console.log(data))
+* @returns {Promise<Object>} - returns boolean if no options are provided, otherwise returns object of results
 */
 TuyaDevice.prototype.get = function (options) {
   let currentDevice;
@@ -145,9 +164,17 @@ TuyaDevice.prototype.get = function (options) {
 
 /**
 * Sets the device's status.
-* @param {boolean} on - `true` for on, `false` for off
-* {id, set: true|false, dps:1}
-* @param {function(error, result)} callback - returns `true` if the command succeeded
+* @param {Object} options - options for setting properties
+* @param {String} [options.id] - ID of device
+* @param {Boolean} options.set - `true` for on, `false` for off
+* @param {Number} [options.dps] - dps index to change
+* @example
+* // set default property on default device
+* tuya.set({set: true}).then(() => console.log('device was changed'))
+* @example
+* // set custom property on non-default device
+* tuya.set({id: 'xxxxxxxxxxxxxxxxxxxx', 'dps': 2, set: true}).then(() => console.log('device was changed'))
+* @returns {Promise<Boolean>} - returns `true` if the command succeeded
 */
 TuyaDevice.prototype.set = function (options) {
   let currentDevice;
@@ -261,6 +288,7 @@ TuyaDevice.prototype._constructBuffer = function (type, data, command) {
 
 /**
 * Extracts JSON from a raw buffer and returns it as an object.
+* @private
 * @param {Buffer} buffer of data
 * @returns {Object} extracted object
 */