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 f740a2e716ff..d3fe181970c8 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
@@ -30,6 +30,12 @@
 
 /**
  * A Google cloud storage object.
+ *
+ * <p>
+ * Objects of this class are immutable. Operations that modify the blob like {@link #update} and
+ * {@link #copyTo} return a new object. To get a {@code Blob} object with the most recent
+ * information use {@link #reload}.
+ * </p>
  */
 public final class Blob {
 
@@ -151,7 +157,10 @@ public Blob reload(BlobSourceOption... options) {
   /**
    * Update the blob's information. Bucket or blob's name cannot be changed by this method. If you
    * want to rename the blob or move it to a different bucket use the {@link #copyTo} and
-   * {@link #delete} operations. A new {@code Blob} object is returned.
+   * {@link #delete} operations. A new {@code Blob} object is returned. By default no checks are
+   * made on the metadata generation of the current blob. If you want to update the information only
+   * if the current blob metadata are at their latest version use the {@code metagenerationMatch}
+   * option: {@code blob.update(newInfo, BlobTargetOption.metagenerationMatch()}.
    *
    * @param blobInfo new blob's information. Bucket and blob names must match the current ones
    * @param options update options
diff --git a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Bucket.java b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Bucket.java
index 47c16a3646ed..b56824f069f6 100644
--- a/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Bucket.java
+++ b/gcloud-java-storage/src/main/java/com/google/gcloud/storage/Bucket.java
@@ -31,6 +31,12 @@
 
 /**
  * A Google cloud storage bucket.
+ *
+ * <p>
+ * Objects of this class are immutable. Operations that modify the bucket like {@link #update}
+ * return a new object. To get a {@code Bucket} object with the most recent information use
+ * {@link #reload}.
+ * </p>
  */
 public final class Bucket {
 
@@ -91,7 +97,10 @@ public Bucket reload(BucketSourceOption... options) {
 
   /**
    * Update the bucket's information. Bucket's name cannot be changed. A new {@code Bucket} object
-   * is returned.
+   * is returned. By default no checks are made on the metadata generation of the current bucket.
+   * If you want to update the information only if the current bucket metadata are at their latest
+   * version use the {@code metagenerationMatch} option:
+   * {@code bucket.update(newInfo, BucketTargetOption.metagenerationMatch());}
    *
    * @param bucketInfo new bucket's information. Name must match the one of the current bucket
    * @param options update options