Documentation for Blob.update() and Storage.update() methods is confusing/incorrect.

[dmitry-fa]

Documentation for Blob.update(Options...) doesn't include example of usage, the provided examples demonstrate how to use Storage.update(blobInfo). The doc also mentions non existing parameter blobInfo: Original metadata are merged with metadata in the provided blobInfo.
Taking into account the fact that Objects of this class are immutable. this method seems useless.
The documentation should be updated to clarify usage.

Documentation for Storage.update() methods is better but still confusing. The important aspects are not covered:

• The term metadata could be read as blob's information or as blob's user provided metadata
• It's not clarify if blob's generation is updated
• What happens if the preconditions specified by the options fail

Documentation should be aligned with the new Blob/BlobInfo API Doc introduced by #176

[frankyn]

This sounds like a good plan, thanks @dmitry-fa