Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Blob API Doc is confusing #233

Merged
merged 5 commits into from Apr 14, 2020
Merged

Conversation

dmitry-fa
Copy link
Contributor

Fixes #176

@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label Apr 8, 2020
@codecov
Copy link

codecov bot commented Apr 8, 2020

Codecov Report

Merging #233 into master will decrease coverage by 0.06%.
The diff coverage is n/a.

Impacted file tree graph

@@             Coverage Diff              @@
##             master     #233      +/-   ##
============================================
- Coverage     63.50%   63.43%   -0.07%     
  Complexity      540      540              
============================================
  Files            30       30              
  Lines          4762     4762              
  Branches        427      427              
============================================
- Hits           3024     3021       -3     
- Misses         1578     1581       +3     
  Partials        160      160              
Impacted Files Coverage Δ Complexity Δ
...e/src/main/java/com/google/cloud/storage/Blob.java 81.97% <ø> (ø) 29.00 <0.00> (ø)
...c/main/java/com/google/cloud/storage/BlobInfo.java 88.95% <ø> (ø) 88.00 <0.00> (ø)
...gle/cloud/storage/testing/RemoteStorageHelper.java 61.47% <0.00%> (-2.46%) 9.00% <0.00%> (ø%)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 397fcd9...4d37e98. Read the comment docs.

@dmitry-fa dmitry-fa requested review from elharo and frankyn April 8, 2020 15:28
* set of properties inherited from the {@link BlobInfo} class and the {@code Storage} instance. The
* class provides methods to perform operations on the object. Reading a property value does not
* issue any RPC calls. The object content is not stored within the {@code Blob} instance,
* operations on obtaining the content will issue one or multiple RPC calls, depending on the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Operations that access the content issue...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done. But access the content issue might sound confusing.

@@ -52,12 +52,26 @@
import java.util.concurrent.TimeUnit;

/**
* A Google cloud storage object.
* A Google cloud storage object. A {@code Blob} object includes the {@code BlobId} instance, the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be very careful with the word "object". This is very easy to confuse wit an instance of the Storage class. I suggest using the phrase "an object in Google Cloud Storage" when you mean the bytes on the server rather than "storage object" which sounds like an instance of a class.

The overloading of the word "object" is really annoying. GCS should never have called these things "objects" but that ship, I am afraid, has sailed and we can't fix it here. :-(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agree

@dmitry-fa dmitry-fa added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Apr 13, 2020
@yoshi-kokoro yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Apr 13, 2020
* BlobInfo} and declares methods to perform operations on the object. Neither {@code BlobInfo} nor
* {@code Blob} instances keep the object content, just the object properties.
*
* <p>Example of usage {@code BlobInfo} to crate an object in Google Cloud Storage:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

crate --> create

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot!

Copy link
Member

@frankyn frankyn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@frankyn frankyn merged commit b5208b8 into googleapis:master Apr 14, 2020
@dmitry-fa dmitry-fa deleted the BlobDoc branch June 26, 2020 07:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Blob API Doc is confusing
5 participants