Blob API Doc is confusing

[elharo]

I'm not sure if the issue is the docs, the API design, or both. However I'm having real trouble understanding the API of this class.

In particular I'm confused about what Blob objects are and what they represent. On the one hand "A Google cloud storage object." On the other hand these objects are immutable and provide methods to modify the blob on GCS which return new Blob objects.

I suspect the Javadoc is having trouble distinguishing an object that points to the thing from the thing itself.

A Google cloud storage object.

Objects of this class are immutable. Operations that modify the blob like update(com.google.cloud.storage.Storage.BlobTargetOption...) and copyTo(com.google.cloud.storage.BlobId, com.google.cloud.storage.Blob.BlobSourceOption...) return a new object. To get a Blob object with the most recent information use reload(com.google.cloud.storage.Blob.BlobSourceOption...). Blob adds a layer of service-related functionality over BlobInfo.