docs: add JSDoc to main interface and resources

Begin to document the project with JSDoc code blocks.

Author: terinjokes

.travis.yml

@@ -37,3 +37,13 @@ jobs:
           skip_cleanup: true
           on:
             tags: true
+    - stage: release
+      node_js: 8
+      script:
+        - npm install -g documentation@^5.3.5
+        - documentation build index.js --format html --output documentation
+      deploy:
+        provider: pages
+        skip_cleanup: true
+        github_token: $GITHUB_TOKEN
+        local_dir: documentation

README.md

@@ -51,24 +51,6 @@ async function getZoneStatus(id) {
 }
 ```
 
-### Available resources and methods
-
-* dnsRecords
-    * `browse(zoneId)`
-    * `read(zoneId, dnsRecordId)`
-    * `edit(zoneId, dnsRecordId, params)`
-    * `add(zoneId, params)`
-    * `del(zoneId, dnsRecordId)`
-* ips
-    * `browse()`
-* zones
-    * `browse()`
-    * `read(zoneId)`
-    * `edit(zoneId, params)`
-    * `add(params)`
-    * `del(zoneId)`
-    * `activationCheck(zoneId)`
-    * `purgeCache(zoneId, params)`
-* user
-    * `read()`
-    * `edit(params)`
+### Documentation
+
+* [Generated JSDoc](https://cloudflare.github.io/node-cloudflare)

index.js

@@ -13,6 +13,21 @@ var resources = {
   user: require('./lib/resources/User')
 };
 
+/**
+ * Constructs and returns a new Cloudflare API client with the specified authentication.
+ *
+ * @class Cloudflare
+ * @param {Object} auth - The API authentication for an account
+ * @param {string} auth.email - The account email address
+ * @param {string} auth.key - The account API token key
+ *
+ * @property {DNSRecords} dnsRecords - DNS Records instance
+ * @property {IPs} ips - IPs instance
+ * @property {Zones} zones - Zones instance
+ * @property {ZoneSettings} zoneSettings - Zone Settings instance
+ * @property {ZoneCustomHostNames} zoneCustomHostNames - Zone Custom Host Names instance
+ * @property {User} user - User instance
+ */
 var Cloudflare = auto(prototypal({
   constructor: function (auth) {
     var client = new Client({

lib/Resource.js

@@ -23,29 +23,43 @@ var BASIC_METHODS = {
   })
 };
 
-module.exports = prototypal({
-  constructor: function (client) {
-    Object.defineProperty(this, '_client', {
-      value: client,
-      writable: false,
-      enumerable: false,
-      configurable: false
-    });
+/**
+ * Resource generates basic methods defined on subclasses. It is not intended to
+ * be constructed directly.
+ *
+ * @class Resource
+ * @private
+ */
+module.exports = prototypal(
+  /** @lends Resource.prototype */
+  {
+    constructor: function (client) {
+      Object.defineProperty(this, '_client', {
+        value: client,
+        writable: false,
+        enumerable: false,
+        configurable: false
+      });
 
-    if (Array.isArray(this.includeBasic)) {
-      this.includeBasic.forEach(function (m) {
-        Object.defineProperty(this, m, {
-          value: BASIC_METHODS[m],
-          writable: true,
-          enumberable: false,
-          configurable: true
-        });
-      }, this);
-    }
-  },
-  createFullPath: function (methodPath) {
-    return (methodPath && [this.path, methodPath].join('/')) || this.path;
-  },
-  path: '',
-  hasBrokenPatch: false
-});
+      if (Array.isArray(this.includeBasic)) {
+        this.includeBasic.forEach(function (m) {
+          Object.defineProperty(this, m, {
+            value: BASIC_METHODS[m],
+            writable: true,
+            enumberable: false,
+            configurable: true
+          });
+        }, this);
+      }
+    },
+  /**
+   * @param {string} methodPath - The path from the {@link method} that should be
+   *        joined with the resource's path.
+   */
+    createFullPath: function (methodPath) {
+      return (methodPath && [this.path, methodPath].join('/')) || this.path;
+    },
+    path: '',
+    hasBrokenPatch: false
+  }
+);

lib/resources/DNSRecords.js

@@ -5,6 +5,13 @@ var auto = require('autocreate');
 var Resource = require('../Resource');
 var method = require('../method');
 
+/**
+ * DNSRecords represents the /zones/:zoneID/dns_records API endpoint.
+ *
+ * @class DNSRecords
+ * @hideconstructor
+ * @extends Resource
+ */
 module.exports = auto(prototypal({
   extends: Resource,
   path: 'zones/:zoneId/dns_records',
@@ -16,8 +23,64 @@ module.exports = auto(prototypal({
     'del'
   ],
 
+  /**
+   * edit allows for modification of the specified DNS Record
+   *
+   * @function edit
+   * @memberof DNSRecords
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The DNS record ID being modified
+   * @param {Object} record - The modified dns record object
+   * @returns {Promise<Object>} The DNS record object.
+   */
   edit: method({
     method: 'PUT',
     path: '/:id'
   })
+
+  /**
+   * browse allows for listing all DNS Records for a zone
+   *
+   * @function browse
+   * @memberof DNSRecords
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @returns {Promise<Object>} The DNS browser response object.
+   */
+  /**
+   * read allows for retrieving the specified DNS Record
+   *
+   * @function read
+   * @memberof DNSRecords
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The DNS record ID
+   * @returns {Promise<Object>} The DNS record object.
+   */
+  /**
+   * add allows for creating a new DNS record for a zone.
+   *
+   * @function add
+   * @memberof DNSRecords
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {Object} record - The new DNS record object
+   * @returns {Promise<Object>} The created DNS record object.
+   */
+  /**
+   * del allows for deleting the specified DNS Record
+   *
+   * @function del
+   * @memberof DNSRecords
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The DNS record ID to delete
+   * @returns {Promise<Object>} The deleted DNS record object.
+   */
 }));

lib/resources/IPs.js

@@ -4,11 +4,33 @@ var auto = require('autocreate');
 
 var Resource = require('../Resource');
 
-module.exports = auto(prototypal({
-  extends: Resource,
-  path: 'ips',
-
-  includeBasic: [
-    'browse'
-  ]
-}));
+/**
+ * IPs represents the /ips API endpoint.
+ *
+ * @class IPs
+ * @hideconstructor
+ * @extends Resource
+ */
+module.exports = auto(prototypal(
+  {
+    extends: Resource,
+    path: 'ips',
+
+    includeBasic: [
+      'browse'
+    ]
+
+  /**
+   * browse returns a Promise of the current Cloudflare IPv4 and IPv6 addresses.
+   *
+   * @function browse
+   * @memberof IPs
+   * @instance
+   * @async
+   * @returns {Promise<Object>} The IPv4 and IPv6 addresses
+   * @example
+   * // logs the fetched IP addresses
+   * cf.ips.browse(console.log)
+   */
+  }
+));

lib/resources/User.js

@@ -5,15 +5,43 @@ var auto = require('autocreate');
 var Resource = require('../Resource');
 var method = require('../method');
 
-module.exports = auto(prototypal({
-  extends: Resource,
-  path: 'user',
+/**
+ * User represents the /user API endpoint.
+ *
+ * @class User
+ * @hideconstructor
+ * @extends Resource
+ */
+module.exports = auto(prototypal(
+  {
+    extends: Resource,
+    path: 'user',
 
-  read: method({
-    method: 'GET'
-  }),
+  /**
+   * read returns the current user object
+   *
+   * @function read
+   * @memberof User
+   * @instance
+   * @async
+   * @returns {Promise<Object>} The user object
+   */
+    read: method({
+      method: 'GET'
+    }),
 
-  edit: method({
-    method: 'PATCH'
-  })
-}));
+  /**
+   * edit allows for modification of the current user
+   *
+   * @function edit
+   * @memberof User
+   * @instance
+   * @async
+   * @param {Object} user - The modified user object
+   * @returns {Promise<Object>} The user object
+   */
+    edit: method({
+      method: 'PATCH'
+    })
+  }
+));

lib/resources/ZoneCustomHostNames.js

@@ -4,6 +4,13 @@ var auto = require('autocreate');
 
 var Resource = require('../Resource');
 
+/**
+ * ZoneCustomHostNames represents the /zones/:zoneID/custom_hostnames API endpoint.
+ *
+ * @class ZoneCustomHostNames
+ * @hideconstructor
+ * @extends Resource
+ */
 module.exports = auto(prototypal({
   extends: Resource,
   path: 'zones/:zoneId/custom_hostnames',
@@ -15,4 +22,60 @@ module.exports = auto(prototypal({
     'add',
     'del'
   ]
+
+  /**
+   * browse allows for listing all of a zone's custom hostanames
+   *
+   * @function browse
+   * @memberof ZoneCustomHostNames
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @returns {Promise<Object>} The custom hostname browse response object.
+   */
+  /**
+   * read allows for retrieving a specific custom hostname
+   *
+   * @function read
+   * @memberof ZoneCustomHostNames
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The custom hostname ID
+   * @returns {Promise<Object>} The custom hostname response object.
+   */
+  /**
+   * edit allows for modifying a specific zone
+   *
+   * @function edit
+   * @memberof ZoneCustomHostNames
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The custom hostname ID
+   * @param {Object} config - The modified custom hostname object
+   * @returns {Promise<Object>} The custom hostname response object.
+   */
+  /**
+   * add allows for creating a new zone
+   *
+   * @function add
+   * @memberof ZoneCustomHostNames
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {Object} config - The new custom hostname object
+   * @returns {Promise<Object>} The custom hostname response object.
+   */
+  /**
+   * del allows for removing a new zone
+   *
+   * @function del
+   * @memberof ZoneCustomHostNames
+   * @instance
+   * @async
+   * @param {string} zone_id - The zone ID
+   * @param {string} id - The custom hostname ID to delete
+   * @returns {Promise<Object>} The custom hostname response object.
+   */
 }));