Updated docs

api/auth-store.js

@@ -1,6 +1,6 @@
 /**
  * Memory store for API key and token.
- * @module auth-store
+ * @module planet-client/api/auth-store
  * @private
  */
 

api/auth.js

@@ -1,6 +1,6 @@
 /**
- * Provides methods for setting API authentication credentials.
- * @module auth
+ * Provides methods for authenticating with a Planet API account.
+ * @module planet-client/api/auth
  */
 
 var errors = require('./errors');
@@ -9,9 +9,10 @@ var store = require('./auth-store');
 var urls = require('./urls');
 
 /**
- * Submit credentials for authentication.
- * @param {string} email Email.
- * @param {string} password Password.
+ * Submit credentials for authentication.  Upon successful authentication, a
+ * token representing the user will be stored for subsequent API requests.
+ * @param {string} email The email associated with a Planet account.
+ * @param {string} password The password for a Planet account.
  * @return {Promise} A promise that resolves on successful login and is rejected
  *     otherwise.
  */
@@ -47,7 +48,9 @@ function logout() {
 }
 
 /**
- * Set an API key to be used for subsequent requests.
+ * Set an API key to be used for subsequent requests.  This is an alternative
+ * to submitting credentials with the [`login`](#module:planet-client/api/auth~login)
+ * method.  The stored key will be used for subsequent API requests.
  * @param {string} key An API key.
  */
 function setKey(key) {

api/errors.js

@@ -1,32 +1,58 @@
 /**
- * Includes specific Error types generated by API requests.
- * @module errors
- * @private
+ * Includes specific `Error` types generated by API requests.  When a request
+ * method returns a promise that is rejected, you can use `instanceof` to
+ * determine what type of error you have.
+ *
+ * @module planet-client/api/errors
  */
 
 /**
- * An error based on a server response.
+ * The base class for all response errors.
  * @param {string} message Error message.
  * @param {XMLHttpRequest} response The response.
  * @param {string} body Any parsed response body.
  * @constructor
+ * @ignore
  */
 function ResponseError(message, response, body) {
+
+  /**
+   * A message providing details about the error.
+   * @type {string}
+   */
   this.message = message;
+
+  /**
+   * The server response.
+   * @type {IncomingMessage}
+   */
   this.response = response;
+
+  /**
+   * Any parsed response body.  For "expected" errors, this will be an object
+   * representing the JSON response body.
+   * @type {Object}
+   */
   this.body = body;
+
+  /**
+   * The stack trace for the error.
+   * @type {string}
+   */
   this.stack = (new Error()).stack;
+
 }
 ResponseError.prototype = new Error();
 ResponseError.prototype.name = 'ResponseError';
 
 /**
- * The request was bad (400).
+ * The request was bad (status `400`).
  * @param {string} message Error message.
  * @param {XMLHttpRequest} response The response.
  * @param {Object} body Any parsed response body (as JSON).
- * @extends {ResponseError}
+ * @extends {module:planet-client/api/errors~ResponseError}
  * @constructor
+ * @ignore
  */
 function BadRequest(message, response, body) {
   ResponseError.apply(this, arguments);
@@ -36,12 +62,13 @@ BadRequest.prototype = new ResponseError();
 BadRequest.prototype.name = 'BadRequest';
 
 /**
- * The request requires user authentication (401).
+ * The request requires user authentication (status `401`).
  * @param {string} message Error message.
  * @param {XMLHttpRequest} response The response.
  * @param {Object} body Any parsed response body (as JSON).
- * @extends {ResponseError}
+ * @extends {module:planet-client/api/errors~ResponseError}
  * @constructor
+ * @ignore
  */
 function Unauthorized(message, response, body) {
   ResponseError.apply(this, arguments);
@@ -51,12 +78,13 @@ Unauthorized.prototype = new ResponseError();
 Unauthorized.prototype.name = 'Unauthorized';
 
 /**
- * The client is forbidden from making the request (403).
+ * The client is forbidden from making the request (status `403`).
  * @param {string} message Error message.
  * @param {XMLHttpRequest} response The response.
  * @param {Object} body Any parsed response body (as JSON).
- * @extends {ResponseError}
+ * @extends {module:planet-client/api/errors~ResponseError}
  * @constructor
+ * @ignore
  */
 function Forbidden(message, response, body) {
   ResponseError.apply(this, arguments);
@@ -70,8 +98,9 @@ Forbidden.prototype.name = 'Forbidden';
  * @param {string} message Error message.
  * @param {XMLHttpRequest} response The response.
  * @param {string} body Any parsed response body.
- * @extends {ResponseError}
+ * @extends {module:planet-client/api/errors~ResponseError}
  * @constructor
+ * @ignore
  */
 function UnexpectedResponse(message, response, body) {
   ResponseError.apply(this, arguments);
@@ -81,9 +110,10 @@ UnexpectedResponse.prototype = new ResponseError();
 UnexpectedResponse.prototype.name = 'UnexpectedResponse';
 
 /**
- * An error generated when the request is aborted.
+ * An error generated when the request is terminated.
  * @param {string} message Error message.
  * @constructor
+ * @ignore
  */
 function AbortedRequest(message) {
   this.message = message;

api/mosaics.js

@@ -1,6 +1,6 @@
 /**
  * Provides methods for getting scene metadata.
- * @module mosaics
+ * @module planet-client/api/mosaics
  */
 
 var Page = require('./page');
@@ -17,7 +17,9 @@ var util = require('./util');
  * @param {function(function())} options.terminator A function that is called
  *     with a function that can be called back to terminate the request.
  * @return {Promise.<Object>} A promise that resolves to mosaic metadata or is
- *     rejected with any error.
+ *     rejected with any error.  See the [`errors`
+ *     module](#module:planet-client/api/errors) for a list of the possible
+ *     error types.
  */
 function get(id, options) {
   options = options || {};
@@ -41,8 +43,10 @@ function get(id, options) {
  *     resources in the response.  True by default.
  * @param {function(function())} options.terminator A function that is called
  *     with a function that can be called back to terminate the request.
- * @return {Promise.<Page>} A promise that resolves to a page of mosaic
- *     metadata or is rejected with any error.
+ * @return {Promise.<module:planet-client/api/page~Page>} A promise that
+ *     resolves to a page of mosaic metadata or is rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function search(query, options) {
   options = options || {};

api/page.js

@@ -1,7 +1,6 @@
 /**
  * Provides a utility for working with pages of search results.
- * @module page
- * @private
+ * @module planet-client/api/page
  */
 
 var url = require('url');
@@ -13,26 +12,26 @@ var url = require('url');
  * @param {function(Object):Promise} factory Function that creates a promise of
  *     new data given a query object.
  * @constructor
+ * @ignore
  */
 function Page(data, factory) {
   var links = data.links;
 
   /**
-   * Get the previous page.  If there is no previous page, `previous` will be
-   *     `null`.
+   * Get the previous page.  If there is no previous page, `prev` will be
+   * `null`.
    * @param {Object} options Any request options.
-   * @return {Promise.<Page>} The previous page.
+   * @return {Promise.<module:planet-client/api/page~Page>} The previous page.
    * @method
    */
   this.prev = !links.prev ? null : function(options) {
     return factory(url.parse(links.prev, true).query, options);
   };
 
   /**
-   * Get the next page.
+   * Get the next page.  If there is no next page, `next` will be `null`.
    * @param {Object} options Any request options.
-   * @return {Promise.<Page>} The next page.  If there is no next page,
-   *     `next` will be `null`.
+   * @return {Promise.<module:planet-client/api/page~Page>} The next page.
    * @method
    */
   this.next = !links.next ? null : function(options) {

api/quads.js

@@ -1,6 +1,6 @@
 /**
  * Provides methods for getting mosaic quad metadata.
- * @module quads
+ * @module planet-client/api/quads
  */
 
 var Page = require('./page');
@@ -19,6 +19,8 @@ var util = require('./util');
  *     with a function that can be called back to terminate the request.
  * @return {Promise.<Object>} A promise that resolves to quad metadata or is
  *     rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function get(mosaicId, quadId, options) {
   options = options || {};
@@ -43,8 +45,10 @@ function get(mosaicId, quadId, options) {
  *     resources in the response.  True by default.
  * @param {function(function())} options.terminator A function that is called
  *     with a function that can be called back to terminate the request.
- * @return {Promise.<Page>} A promise that resolves to a page of quad
- *     metadata or is rejected with any error.
+ * @return {Promise.<module:planet-client/api/page~Page>} A promise that
+ *     resolves to a page of quad metadata or is rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function search(mosaicId, query, options) {
   options = options || {};
@@ -75,6 +79,8 @@ function search(mosaicId, query, options) {
  *     with a function that can be called back to terminate the request.
  * @return {Promise.<Object>} A promise that resolves to quad metadata or is
  *     rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function scenes(mosaicId, quadId, options) {
   options = options || {};

api/request.js

@@ -1,6 +1,6 @@
 /**
  * Provides methods for issuing API requests.
- * @module requests
+ * @module planet-client/api/request
  * @private
  */
 

api/scenes.js

@@ -1,6 +1,6 @@
 /**
  * Provides methods getting scene metadata.
- * @module scenes
+ * @module planet-client/api/scenes
  */
 
 var Page = require('./page');
@@ -20,6 +20,8 @@ var util = require('./util');
  *     with a function that can be called back to terminate the request.
  * @return {Promise.<Object>} A promise that resolves to scene metadata or is
  *     rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function get(scene, options) {
   options = options || {};
@@ -49,8 +51,10 @@ function get(scene, options) {
  *     resources in the response.  True by default.
  * @param {function(function())} options.terminator A function that is called
  *     with a function that can be called back to terminate the request.
- * @return {Promise.<Page>} A promise that resolves to a page of scene
- *     metadata or is rejected with any error.
+ * @return {Promise.<module:planet-client/api/page~Page>} A promise that
+ *     resolves to a page of scene metadata or is rejected with any error.
+ *     See the [`errors` module](#module:planet-client/api/errors) for a list of
+ *     the possible error types.
  */
 function search(query, options) {
   options = options || {};

api/urls.js

@@ -1,6 +1,6 @@
 /**
  * API URL utilities.
- * @module urls
+ * @module planet-client/api/urls
  * @private
  */
 

api/util.js

@@ -1,6 +1,6 @@
 /**
  * General utilities.
- * @module util
+ * @module planet-client/api/util
  * @private
  */
 

api/workspaces.js

@@ -1,6 +1,6 @@
 /**
  * Provides methods for working with workspaces.
- * @module workspaces
+ * @module planet-client/api/workspaces
  * @private
  */
 

cli/find-mosaics.js

@@ -2,7 +2,8 @@ var mosaics = require('../api/mosaics');
 
 /**
  * Recursively fetch all pages until the limit is reached.
- * @param {Promise.<Page>} promise A promise that resolves to a page of mosaics.
+ * @param {Promise.<module:planet-client/api/page~Page>} promise A promise that
+ *     resolves to a page of mosaics.
  * @param {Array} list An array of mosaic metadata.
  * @param {number} limit The limit.
  * @return {Promise.<Array>} An array that resolves to an array of mosaics.

cli/find-quads.js

@@ -44,7 +44,8 @@ function resolveQuery(opts) {
 
 /**
  * Recursively fetch all pages until the limit is reached.
- * @param {Promise.<Page>} promise A promise that resolves to a page of quads.
+ * @param {Promise.<module:planet-client/api/page~Page>} promise A promise that
+ *     resolves to a page of quads.
  * @param {Array} features An array of quad metadata.
  * @param {number} limit The limit.
  * @return {Promise.<Array>} An array that resolves to an array of quads.

cli/find-scenes.js

@@ -133,7 +133,8 @@ function resolveQuery(opts) {
 
 /**
  * Recursively fetch all pages until the limit is reached.
- * @param {Promise.<Page>} promise A promise that resolves to a page of scenes.
+ * @param {Promise.<module:planet-client/api/page~Page>} promise A promise that
+ *     resolves to a page of scenes.
  * @param {Array} features An array of scene metadata.
  * @param {number} limit The limit.
  * @return {Promise.<Array>} An array that resolves to an array of scenes.