Document AWS.AWSResponse

lib/promise.js

@@ -71,6 +71,8 @@ var inherit = AWS.util.inherit;
  *   }, {bind: myContext});
  *
  * The above callback will print +true+ when the callback function is executed.
+ *
+ * @see AWS.AWSResponse
  */
 AWS.AWSRequest = inherit({
   /**
@@ -299,8 +301,107 @@ AWS.AWSRequest = inherit({
 
 });
 
+/**
+ * This class encapsulates the the response information
+ * from a service request operation sent through {AWS.AWSRequest}.
+ * The response object has two main properties for getting information
+ * back from a request:
+ *
+ * == The +data+ property
+ *
+ * The +response.data+ property contains the serialized object data
+ * retrieved from the service request. For instance, for an
+ * Amazon DynamoDB +listTables+ method call, the response data might
+ * look like:
+ *
+ *   > resp.data
+ *   { TableNames:
+ *      [ 'table1', 'table2', ... ] }
+ *
+ * The +data+ property can be null if an error occurs (see below).
+ *
+ * == The +error+ property
+ *
+ * In the event of a service error (or transfer error), the
+ * +response.error+ property will be filled with the given
+ * error data in the form:
+ *
+ *   { code: 'SHORT_UNIQUE_ERROR_CODE',
+ *     message: 'Some human readable error message' }
+ *
+ * In the case of an error, the +data+ property will be +null+.
+ * Note that if you handle events that can be in a failure state,
+ * you should always check whether +response.error+ is set
+ * before attempting to access the +response.data+ property.
+ *
+ * @!attribute data
+ *   @readonly
+ *   @group Data Properties
+ *   @note Inside of a {AWS.AWSRequest.data} event, this
+ *     property contains a single raw packet instead of the
+ *     full de-serialized service response.
+ *   @return [Object] the de-serialized response data
+ *     from the service.
+ *
+ * @!attribute error
+ *   An structure containing information about a service
+ *   or networking error.
+ *   @readonly
+ *   @group Data Properties
+ *   @note This attribute is only filled if a service or
+ *     networking error occurs.
+ *   @return [Object]
+ *     * code [String] a unique short code representing the
+ *       error that was emitted.
+ *     * message [String] a longer human readable error message
+ *     * retryable [Boolean] whether the error message is
+ *       retryable.
+ *
+ * @!attribute client
+ *   @readonly
+ *   @group Operation Properties
+ *   @return [AWS.Client] The low-level service client object
+ *     that initiated the request.
+ *
+ * @!attribute method
+ *   @readonly
+ *   @group Operation Properties
+ *   @return [String] the name of the operation executed on
+ *     the service.
+ *
+ * @!attribute params
+ *   @readonly
+ *   @group Operation Properties
+ *   @return [Object] the parameters sent in the request to
+ *     the service.
+ *
+ * @!attribute retryCount
+ *   @readonly
+ *   @group Operation Properties
+ *   @return [Integer] the number of retries that have were
+ *     attempted before the request was completed.
+ *
+ * @!attribute httpRequest
+ *   @readonly
+ *   @group HTTP Properties
+ *   @return [AWS.HttpRequest] the raw HTTP request object
+ *     containing request headers and body information
+ *     sent by the client.
+ *
+ * @!attribute httpResponse
+ *   @readonly
+ *   @group HTTP Properties
+ *   @return [AWS.HttpResponse] the raw HTTP response object
+ *     containing the response headers and body information
+ *     from the server.
+ *
+ * @see AWS.AWSRequest
+ */
 AWS.AWSResponse = inherit({
 
+  /**
+   * @api private
+   */
   constructor: function AWSResponse(options) {
 
     // the request "context"