Improve JSDoc of updateWorkspaceFolders

[weinand]

testing #42195:

The JSDoc of updateWorkspaceFolders explains what you can do with it but not what it actually does.
I suggest to add something like the following as the first sentence:

"On the array 'vscode.workspace.workspaceFolders' this method replaces 'deleteCount' folders starting at index 'start' by an optional set of 'workspaceFoldersToAdd'. This "splice" behavior can be used to add, remove and change workspace folders in a single operation."

In addition I suggest to explicitly state that the code that changes the first folder is aborted immediately. So the extension must be prepared to recover from this situation. Just reading an innocent sentence like "all extensions will be restarted" does not make this problem clear.

[bpasero]

@weinand