fix: documentation for blob.update() and storage.update() methods is confusing/incorrect

dmitry-fa · dmitry-fa · commit b97e5fe14ba2 · 2020-04-16T14:23:40.000+03:00
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Blob.java
@@ -546,9 +546,9 @@ public Blob reload(BlobSourceOption... options) {
   }
 
   /**
-   * Updates the blob properties. Optional {@code options} parameter specifies the preconditions for
-   * applying the update. To update the properties you need to call {@link #toBuilder()}, set the
-   * properties you want to change, build the new {@code Blob} instance and then call {@link
+   * Updates the blob properties. Optional {@code options} parameter can contain the preconditions
+   * for applying the update. To update the properties you need to call {@link #toBuilder()}, set
+   * the properties you want to change, build the new {@code Blob} instance and then call {@link
    * #update(BlobTargetOption...)}.
    *
    * <p>The property update details are described in {@link Storage#update(BlobInfo)}. {@link
diff --git a/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java b/google-cloud-storage/src/main/java/com/google/cloud/storage/Storage.java
@@ -1992,8 +1992,8 @@ Blob create(
    * Updates the blob properties if the preconditions specified by {@code options} are met. The
    * property update works as described in {@link #update(BlobInfo)}.
    *
-   * <p>{@code options} parameter allows to specify the preconditions for applying the update. E.g.
-   * update of the blob properties might be required only if the properties have not been updated
+   * <p>{@code options} parameter can contain the preconditions for applying the update. E.g. update
+   * of the blob properties might be required only if the properties have not been updated
    * externally. {@code StorageException} with the code {@code 412} is thrown if preconditions fail.
    *
    * <p>Example of updating the content type only if the properties are not updated externally:

Original file line number	Diff line number	Diff line change
`@@ -546,9 +546,9 @@ public Blob reload(BlobSourceOption... options) {`
`546`	`546`	`}`
`547`	`547`
`548`	`548`	`/**`
`549`		`-* Updates the blob properties. Optional {@code options} parameter specifies the preconditions for`
`550`		`-* applying the update. To update the properties you need to call {@link #toBuilder()}, set the`
`551`		`-* properties you want to change, build the new {@code Blob} instance and then call {@link`
	`549`	`+* Updates the blob properties. Optional {@code options} parameter can contain the preconditions`
	`550`	`+* for applying the update. To update the properties you need to call {@link #toBuilder()}, set`
	`551`	`+* the properties you want to change, build the new {@code Blob} instance and then call {@link`
`552`	`552`	`* #update(BlobTargetOption...)}.`
`553`	`553`	`*`
`554`	`554`	`* <p>The property update details are described in {@link Storage#update(BlobInfo)}. {@link`
Original file line number	Diff line number	Diff line change
`@@ -1992,8 +1992,8 @@ Blob create(`
`1992`	`1992`	`* Updates the blob properties if the preconditions specified by {@code options} are met. The`
`1993`	`1993`	`* property update works as described in {@link #update(BlobInfo)}.`
`1994`	`1994`	`*`
`1995`		`-* <p>{@code options} parameter allows to specify the preconditions for applying the update. E.g.`
`1996`		`-* update of the blob properties might be required only if the properties have not been updated`
	`1995`	`+* <p>{@code options} parameter can contain the preconditions for applying the update. E.g. update`
	`1996`	`+* of the blob properties might be required only if the properties have not been updated`
`1997`	`1997`	`* externally. {@code StorageException} with the code {@code 412} is thrown if preconditions fail.`
`1998`	`1998`	`*`
`1999`	`1999`	`* <p>Example of updating the content type only if the properties are not updated externally:`