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.

nodejs-storage/src/nodejs-common/service-object.ts

Lines 477 to 485 in 57b28f1

	/**
	* Set the metadata for this object.
	*
	* @param {object} metadata - The metadata to set on this object.
	* @param {object=} options - Configuration options.
	* @param {function=} callback - The callback function.
	* @param {?error} callback.err - An error returned while making this request.
	* @param {object} callback.apiResponse - The full API response.
	*/

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:

nodejs-storage/src/file.ts

Lines 943 to 949 in 57b28f1

	* Merge the given metadata with the current remote file's metadata. This
	* will set metadata if it was previously unset or update previously set
	* metadata. To unset previously set metadata, set its value to null.
	*
	* You can set custom key/value pairs in the metadata key of the given
	* object, however the other properties outside of this object must adhere
	* to the {@link https://goo.gl/BOnnCK| official API documentation}.

We are working to resolve the issue.