Add documentation for client usage.

lib/digitalocean/client.js

@@ -21,9 +21,29 @@
   var slice = [].slice,
     DigitalOceanError = require('./error');
 
+  /**
+    * Client resource
+    * @class Client
+    */
   var Client = (function() {
-    // token, required, string
-    // options, optional
+    /**
+     * @typedef ClientOptions
+     * @type {object}
+     * @property {object} [request] - pass in a specific version of the request library.
+     * @property {object} [promise] - pass in a specific version of promise library.
+     * @property {object} [requestOptions] - a base set of options provided to Request, overridden by options passed to a specific API method. defaults to empty object.
+     * @property {string} [protocol] - defaults to https.
+     * @property {string} [hostname] - defaults to api.digitalocean.com.
+     * @property {string} [port] - defaults to protocol default (e.g. with a protocol of https defaults to 443).
+     */
+
+    /**
+     * Create a new Client instance.
+     *
+     * @param {string} token - The DigitalOcean token used for authorization.
+     * @param {ClientOptions} [options] - An object whose values are used to configure a client instance.
+     * @memberof Client
+     */
     function Client(token, options) {
       this.token = token;
       this.options = options;
@@ -184,13 +204,18 @@
       return deferred;
     };
 
-    // path, required, string
-    // options, required
-    // page or query object, optional
-    // perPage, optional
-    // successStatuses, required, number or array of numbers
-    // successRootKeys, required, string or array of strings
-    // callback, required, function
+    /**
+     * Send a HTTP GET request with the specified parameters.
+     *
+     * @param {string} path - the URL escaped route
+     * @param {object} options - an object passed to the request library  See the {@link https://github.com/request/request#requestoptions-callback|request docs} for valid attributes, e.g. a proxy or user agent
+     * @param {(number|object)} [page or queryObject] - page number to retrieve or key value pairs of query parameters
+     * @param {number} [perPage] - number of result per page to retrieve
+     * @param {number|number[]} successStatuses - number or array of numbers corresponding to successful HTTP status codes
+     * @param {string|string[]} successRootKeys - string or array of strings corresponding to the root objects containing successful responses
+     * @param {requestCallback} [callback] - callback that handles the response
+     * @memberof Client
+     */
     Client.prototype.get = function() {
       var i;
       var path = arguments[0],
@@ -257,42 +282,63 @@
       );
     };
 
-    // path, required, string
-    // content, required, object
-    // options, optional, object
-    // successStatuses, required, number or array of numbers
-    // successRootKeys, required, string or array of strings
-    // callback, required, function
+
+    /**
+     * Send a HTTP POST request with the specified parameters.
+     *
+     * @param {string} path - the URL escaped route
+     * @param {object} content - an object serialized to json
+     * @param {object} options - an object passed to the request library  See the {@link https://github.com/request/request#requestoptions-callback|request docs} for valid attributes, e.g. a proxy or user agent
+     * @param {number|number[]} successStatuses - number or array of numbers corresponding to successful HTTP status codes
+     * @param {string|string[]} successRootKeys - string or array of strings corresponding to the root objects containing successful responses
+     * @param {requestCallback} [callback] - callback that handles the response
+     * @memberof Client
+     */
     Client.prototype.post = function(path, content, options, successStatuses, successRootKeys, callback) {
       return this._makeRequestWithBody('POST', path, content, options, successStatuses, successRootKeys, callback);
     };
 
-    // path, required, string
-    // content, required, object
-    // options, optional, object
-    // successStatuses, required, number or array of numbers
-    // successRootKeys, required, string or array of strings
-    // callback, required, function
+    /**
+     * Send a HTTP PATCH request with the specified parameters.
+     *
+     * @param {string} path - the URL escaped route
+     * @param {object} content - an object serialized to json
+     * @param {object} options - an object passed to the request library  See the {@link https://github.com/request/request#requestoptions-callback|request docs} for valid attributes, e.g. a proxy or user agent
+     * @param {number|number[]} successStatuses - number or array of numbers corresponding to successful HTTP status codes
+     * @param {string|string[]} successRootKeys - string or array of strings corresponding to the root objects containing successful responses
+     * @param {requestCallback} [callback] - callback that handles the response
+     * @memberof Client
+     */
     Client.prototype.patch = function(path, content, options, successStatuses, successRootKeys, callback) {
       return this._makeRequestWithBody('PATCH', path, content, options, successStatuses, successRootKeys, callback);
     };
 
-    // path, required, string
-    // content, required, object
-    // options, optional, object
-    // successStatuses, required, number or array of numbers
-    // successRootKeys, required, string or array of strings
-    // callback, required, function
+    /**
+     * Send a HTTP PUT request with the specified parameters.
+     *
+     * @param {string} path - the URL escaped route
+     * @param {object} content - an object serialized to json
+     * @param {object} options - an object passed to the request library  See the {@link https://github.com/request/request#requestoptions-callback|request docs} for valid attributes, e.g. a proxy or user agent
+     * @param {number|number[]} successStatuses - number or array of numbers corresponding to successful HTTP status codes
+     * @param {string|string[]} successRootKeys - string or array of strings corresponding to the root objects containing successful responses
+     * @param {requestCallback} [callback] - callback that handles the response
+     * @memberof Client
+     */
     Client.prototype.put = function(path, content, options, successStatuses, successRootKeys, callback) {
       return this._makeRequestWithBody('PUT', path, content, options, successStatuses, successRootKeys, callback);
     };
 
-    // path, required, string
-    // content, required, object
-    // options, optional, object
-    // successStatuses, required, number or array of numbers
-    // successRootKeys, required, string or array of strings
-    // callback, required, function
+    /**
+     * Send a HTTP DELETE request with the specified parameters.
+     *
+     * @param {string} path - the URL escaped route
+     * @param {object} content - an object serialized to json
+     * @param {object} options - an object passed to the request library  See the {@link https://github.com/request/request#requestoptions-callback|request docs} for valid attributes, e.g. a proxy or user agent
+     * @param {number|number[]} successStatuses - number or array of numbers corresponding to successful HTTP status codes
+     * @param {string|string[]} successRootKeys - string or array of strings corresponding to the root objects containing successful responses
+     * @param {requestCallback} [callback] - callback that handles the response
+     * @memberof Client
+     */
     Client.prototype.delete = function(path, content, options, successStatuses, successRootKeys, callback) {
       return this._makeRequestWithBody('DELETE', path, content, options, successStatuses, successRootKeys, callback);
     };