Correct some yard errors and beef up a few docs

lib/services/s3.js

@@ -734,13 +734,23 @@ AWS.util.update(AWS.S3.prototype, {
 
 
   /**
-   * Get a pre-signed POST policy for a given operation name.
+   * Get a pre-signed POST policy to support uploading to S3 directly from an
+   * HTML form.
    *
    * @param params [map]
-   * @option params.Bucket [String]
-   * @option params.Expires [Number]
-   * @option params.Conditions [Array]
-   * @option params.Fields [map]
+   * @option params Bucket [String]     The bucket to which the post should be
+   *                                    uploaded
+   * @option params Expires [Integer]   (3600) The number of seconds for which
+   *                                    the presigned policy should be valid.
+   * @option params Conditions [Array]  An array of conditions that must be met
+   *                                    for the presigned policy to allow the
+   *                                    upload. This can include required tags,
+   *                                    the accepted range for content lengths,
+   *                                    etc.
+   * @see http://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html
+   * @option params Fields [map]        Fields to include in the form. All
+   *                                    values passed in as fields will be
+   *                                    signed as exact match conditions.
    * @param callback [Function]
    *
    * @note All fields passed in when creating presigned post data will be signed
@@ -786,6 +796,22 @@ AWS.util.update(AWS.S3.prototype, {
    *   this (you are using an asynchronous credential provider, i.e., EC2
    *   IAM roles), you should always call this method with an asynchronous
    *   callback.
+   *
+   * @return [map]  If called synchronously (with no callback), returns a hash
+   *                with the url to set as the form action and a hash of fields
+   *                to include in the form.
+   * @return [null] Nothing is returned if a callback is provided.
+   *
+   * @callback callback function (err, data)
+   *  @param err [Error] the error object returned from the policy signer
+   *  @param data [map] The data necessary to construct an HTML form
+   *  @param data.url [String] The URL to use as the action of the form
+   *  @param data.fields [map] A hash of fields that must be included in the
+   *                           form for the upload to succeed. This hash will
+   *                           include the signed POST policy, your access key
+   *                           ID and security token (if present), etc. These
+   *                           may be safely included as input elements of type
+   *                           'hidden.'
    */
   createPresignedPost: function createPresignedPost(params, callback) {
     if (typeof params === 'function' && callback === undefined) {
@@ -947,6 +973,7 @@ AWS.util.update(AWS.S3.prototype, {
   },
 
   /**
+   * @see AWS.S3.ManagedUpload
    * @overload upload(params = {}, [options], [callback])
    *   Uploads an arbitrarily sized buffer, blob, or stream, using intelligent
    *   concurrent handling of parts if the payload is large enough. You can
@@ -972,11 +999,10 @@ AWS.util.update(AWS.S3.prototype, {
    * @callback callback function(err, data)
    *   @param err [Error] an error or null if no error occurred.
    *   @param data [map] The response data from the successful upload:
-   *     * `Location` (String) the URL of the uploaded object
-   *     * `ETag` (String) the ETag of the uploaded object
-   *     * `Bucket` (String) the bucket to which the object was uploaded
-   *     * `Key` (String) the key to which the object was uploaded
-   *   @see AWS.S3.ManagedUpload
+   *   @param data.Location [String] the URL of the uploaded object
+   *   @param data.ETag [String] the ETag of the uploaded object
+   *   @param data.Bucket [String]  the bucket to which the object was uploaded
+   *   @param data.Key [String] the key to which the object was uploaded
    */
   upload: function upload(params, options, callback) {
     if (typeof options === 'function' && callback === undefined) {

lib/signers/v4_credentials.js

@@ -27,7 +27,7 @@ module.exports = {
    * @param date [String]
    * @param region [String]
    * @param serviceName [String]
-   * @returns {string}
+   * @return [String]
    */
   createScope: function createScope(date, region, serviceName) {
     return [
@@ -46,7 +46,7 @@ module.exports = {
    * @param region [String]
    * @param service [String]
    * @param shouldCache [Boolean]
-   * @returns {String}
+   * @return [String]
    */
   getSigningKey: function getSigningKey(
     credentials,