From 4e0248f951ddc61ae2a5cdb82d1f953f3bba17cb Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Tue, 15 Mar 2016 14:33:27 +0100
Subject: [PATCH] Add better javadoc for signUrl examples

---
 .../java/com/google/gcloud/storage/Blob.java  | 30 +++++++++----------
 .../com/google/gcloud/storage/Storage.java    | 13 ++++----
 2 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java
index c60a703eda91..b4fc892d3df5 100644
--- a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java
+++ b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Blob.java
@@ -456,27 +456,27 @@ public WriteChannel writer(BlobWriteOption... options) {
   /**
    * Generates a signed URL for this blob. If you want to allow access for a fixed amount of time to
    * this blob, you can use this method to generate a URL that is only valid within a certain time
-   * period. This is particularly useful if you don't want publicly accessible blobs, but don't want
-   * to require users to explicitly log in. Signing a URL requires a service account
-   * and its associated private key. If a {@link AuthCredentials.ServiceAccountAuthCredentials} was
-   * passed to {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default
-   * credentials are being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS}
-   * is set, then {@code signUrl} will use that service account and associated key to sign the URL.
-   * If the credentials passed to {@link StorageOptions} do not expose a private key (this is the
-   * case for App Engine credentials, Compute Engine credentials and Google Cloud SDK credentials)
-   * then {@code signUrl} will throw an {@link IllegalArgumentException} unless a service account
-   * with associated key is passed using the {@code SignUrlOption.serviceAccount()} option. The
-   * service account and private key passed with {@code SignUrlOption.serviceAccount()} have
-   * priority over any credentials set with
-   * {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
+   * period. This is particularly useful if you don't want publicly accessible blobs, but also don't
+   * want to require users to explicitly log in. Signing a URL requires a service account and its
+   * associated private key. If a {@link AuthCredentials.ServiceAccountAuthCredentials} was passed
+   * to {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials
+   * are being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
+   * {@code signUrl} will use that service account and associated key to sign the URL. If the
+   * credentials passed to {@link StorageOptions} do not expose a private key (this is the case for
+   * App Engine credentials, Compute Engine credentials and Google Cloud SDK credentials) then
+   * {@code signUrl} will throw an {@link IllegalArgumentException} unless a service account with
+   * associated key is passed using the {@code SignUrlOption.serviceAccount()} option. The service
+   * account and private key passed with {@code SignUrlOption.serviceAccount()} have priority over
+   * any credentials set with {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
    *
-   * <p>Example usage of creating a signed URL that is valid for 2 weeks:
+   * <p>Example usage of creating a signed URL that is valid for 2 weeks, using the default
+   *     credentials for signing the URL:
    * <pre> {@code
    * blob.signUrl(14, TimeUnit.DAYS);
    * }</pre>
    *
    * <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}
-   *     option:
+   *     option, that will be used for signing the URL:
    * <pre> {@code
    * blob.signUrl(14, TimeUnit.DAYS, SignUrlOption.serviceAccount(
    *     AuthCredentials.createForJson(new FileInputStream("/path/to/key.json"))));
diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java
index 91f7578d7f89..7a58878469f1 100644
--- a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java
+++ b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java
@@ -1480,10 +1480,10 @@ private static void checkContentType(BlobInfo blobInfo) throws IllegalArgumentEx
    * Generates a signed URL for a blob. If you have a blob that you want to allow access to for a
    * fixed amount of time, you can use this method to generate a URL that is only valid within a
    * certain time period. This is particularly useful if you don't want publicly accessible blobs,
-   * but don't want to require users to explicitly log in. Signing a URL requires a service account
-   * and its associated private key. If a {@link ServiceAccountAuthCredentials} was passed to
-   * {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials are
-   * being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
+   * but also don't want to require users to explicitly log in. Signing a URL requires a service
+   * account and its associated private key. If a {@link ServiceAccountAuthCredentials} was passed
+   * to {@link StorageOptions.Builder#authCredentials(AuthCredentials)} or the default credentials
+   * are being used and the environment variable {@code GOOGLE_APPLICATION_CREDENTIALS} is set, then
    * {@code signUrl} will use that service account and associated key to sign the URL. If the
    * credentials passed to {@link StorageOptions} do not expose a private key (this is the case for
    * App Engine credentials, Compute Engine credentials and Google Cloud SDK credentials) then
@@ -1492,13 +1492,14 @@ private static void checkContentType(BlobInfo blobInfo) throws IllegalArgumentEx
    * account and private key passed with {@code SignUrlOption.serviceAccount()} have priority over
    * any credentials set with {@link StorageOptions.Builder#authCredentials(AuthCredentials)}.
    *
-   * <p>Example usage of creating a signed URL that is valid for 2 weeks:
+   * <p>Example usage of creating a signed URL that is valid for 2 weeks, using the default
+   *     credentials for signing the URL:
    * <pre> {@code
    * service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS);
    * }</pre>
    *
    * <p>Example usage of creating a signed URL passing the {@code SignUrlOption.serviceAccount()}
-   *     option:
+   *     option, that will be used for signing the URL:
    * <pre> {@code
    * service.signUrl(BlobInfo.builder("bucket", "name").build(), 14, TimeUnit.DAYS,
    *     SignUrlOption.serviceAccount(