Add better javadoc to Storage.copy and CopyWriter

Author: mziccard

gcloud-java-storage/src/main/java/com/google/gcloud/storage/CopyWriter.java

@@ -32,7 +32,13 @@
 import java.util.concurrent.Callable;
 
 /**
- * Google Storage blob copy writer. This class holds the result of a copy request. If source and
+ * Google Storage blob copy writer. A {@code CopyWriter} object allows to copy both blob's data and
+ * information. To override source blob's information call {@link Storage#copy(Storage.CopyRequest)}
+ * with a {@code CopyRequest} object where the copy target is set via
+ * {@link Storage.CopyRequest.Builder#target(BlobInfo, Storage.BlobTargetOption...)} or
+ * {@link Storage.CopyRequest.Builder#target(BlobInfo, Iterable)}.
+ *
+ * <p>This class holds the result of a copy request. If source and
  * destination blobs share the same location and storage class the copy is completed in one RPC call
  * otherwise one or more {@link #copyChunk} calls are necessary to complete the copy. In addition,
  * {@link CopyWriter#result()} can be used to automatically complete the copy and return information

gcloud-java-storage/src/main/java/com/google/gcloud/storage/Storage.java

@@ -1385,12 +1385,17 @@ public static Builder builder() {
   Blob compose(ComposeRequest composeRequest);
 
   /**
-   * Sends a copy request. Returns a {@link CopyWriter} object for the provided
-   * {@code CopyRequest}. If source and destination objects share the same location and storage
-   * class the source blob is copied with one request and {@link CopyWriter#result()} immediately
-   * returns, regardless of the {@link CopyRequest#megabytesCopiedPerChunk} parameter.
-   * If source and destination have different location or storage class {@link CopyWriter#result()}
-   * might issue multiple RPC calls depending on blob's size.
+   * Sends a copy request. This method copies both blob's data and information. To override source
+   * blob's information set the copy target via
+   * {@link CopyRequest.Builder#target(BlobInfo, BlobTargetOption...)} or
+   * {@link CopyRequest.Builder#target(BlobInfo, Iterable)}.
+   *
+   * <p>This method returns a {@link CopyWriter} object for the provided {@code CopyRequest}. If
+   * source and destination objects share the same location and storage class the source blob is
+   * copied with one request and {@link CopyWriter#result()} immediately returns, regardless of the
+   * {@link CopyRequest#megabytesCopiedPerChunk} parameter. If source and destination have different
+   * location or storage class {@link CopyWriter#result()} might issue multiple RPC calls depending
+   * on blob's size.
    *
    * <p>Example usage of copy:
    * <pre> {@code BlobInfo blob = service.copy(copyRequest).result();}