Wrong parameters and examples in FileSystemProvider.getFileForSaving()

[pklaschka]

Expected Behaviour

In uxp/src/pages/uxp/reference-js/Modules/uxp/Persistent File Storage/FileSystemProvider.md, the documentation should reflect the APIs behavior, which (tested in both PS and XD in their current versions) differs between docs and actual behavior. The old XD docs actually document the correct behavior.

What the docs should look like (based on the actual behavior)

getFileForSaving(suggestedName, options)

Gets a file reference suitable for read-write by displaying a "Save" file
picker dialog to the user.

If the act of writing to the file would overwrite it, the file picker
will prompt the user to confirm before returning a result to you.

Returns: Promise<File> - returns the selected file, or null if canceled

Param	Type	Description
suggestedName	string	Required. The file extension should match one of the options specified in the types option.
options	Object
[options.types]	Array<string>	Allowed file extensions, with no "." prefix.
[options.initialDomain]	Symbol	the preferred initial location of the file picker. If not defined, the most recently used domain from a file picker is used instead.

Example

const file = await fs.getFileForSaving("output.txt", { types: [ "txt" ]});
if (!file) {
    // file picker was cancelled
    return;
}
await file.write("It was a dark and stormy night");

Actual Behaviour

Issues with the current documentation:

• suggestedName argument is not mentioned at all, but is required (also in the code example)
• the return type is documented as File, but there's no mention that the function is async => it would probably be the easiest to document the return type as Promise<File>.
• code example contains a syntax error (= has to be : in the options object)
• code example destructures a file array where there is simply no array

=> Overall, without looking back at adobexdplatform.com (or my old code based on the info from there), there would have been no way for me to discover the actual working solution from either the docs or anywhere else (there's also no way to discover correct arguments via dev tools, etc., after all, meaning the only option would have been a lot of trial and error).

Reproduce Scenario (including but not limited to)

Steps to Reproduce

Platform and Version

(both Windows 10)

• XD, 42.0.22
• PS, 22.4.3

Sample Code that illustrates the problem

// from docs example
const [file] = await fs.getFileForSaving({ types = [ "txt" ]}); // syntax error 😜 

// docs without syntax error
const [file] = await fs.getFileForSaving({ types: [ "txt" ]}); // doesn't work, fails silently

// works
const file = await fs.getFileForSaving({ types: [ "txt" ]}); // works

Logs taken while reproducing the problem

n/a

[pklaschka]

(There are also a few similar issues with the other functions, including, but not limited to, a syntax error in the getFileForOpening which, e.g., also includes the code example syntax error; getFileForSasving is just something I recently used and therefore took a closer look at)