docs: Clarify whether setMetadata is replacing existing metadata or updating only specified fields

[IchordeDionysos]

From the NodeJS documentation, it is not clear enough whether calling file.setMetadata({contentType: 'image/png'}) would remove existing metadata fields on the field (as they are not specified) or would only change the content type.

To understand this, one must dig deeply into the NodeJS SDK to understand the exact behaviour and cross-reference it with the Cloud Storage API.

From my understanding, setMetadata is using PATCH, so any existing metadata would stay the same, correct?

--

Could we please update the documentation to make this clearer?

e.g. Set the metadata of the object. Uses PATCH method, meaning it only modifies passed fields and leaves unspecified fields unchanged. https://github.com/googleapis/nodejs-storage/blob/57b28f1123db414c545bc0c1b0a760cf57aa2cb0/src/nodejs-common/service-object.ts#L477-L485

And also mirror those function documentation to the File class method (as otherwise, the documentation will not be surfaced on the SDK API documentation page) See: https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/file#_google_cloud_storage_File_setMetadata_member_1_

[ddelgrosso1]

Thanks for opening an issue. We are aware of a current documentation problem for some functions such as setMetadata where the full documentation is not being displayed. For example, what you are requesting is already present at: https://github.com/googleapis/nodejs-storage/blob/57b28f1123db414c545bc0c1b0a760cf57aa2cb0/src/file.ts#L943-L949

We are working to resolve the issue.