diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index 162f08a5eb2c05eafdbfd465ffa9c7efd2618723..8dc35db72d8ee5d55c753084421dab365466046b 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -159,33 +159,37 @@ declare module 'vscode' {
 		export function registerFileSystemProvider(scheme: string, provider: FileSystemProvider): Disposable;
 
 		/**
-		 * Updates the workspace folders of the currently opened workspace. This method allows to add and remove
-		 * workspace folders a the same time.
+		 * Updates the workspace folders of the currently opened workspace. This method allows to add, remove
+		 * and change workspace folders a the same time.
 		 *
-		 * Example: adding a new workspace folder at the end of workspace folders
+		 * **Example:** adding a new workspace folder at the end of workspace folders
 		 * ```typescript
-		 * workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, [{ uri: ...}])
+		 * workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, [{ uri: ...}]);
 		 * ```
 		 *
-		 * Example: removing the first workspace folder
+		 * **Example:** removing the first workspace folder
 		 * ```typescript
-		 * workspace.updateWorkspaceFolders(0, 1)
+		 * workspace.updateWorkspaceFolders(0, 1);
 		 * ```
 		 *
-		 * Example: replacing an existing workspace folder with a new one
+		 * **Example:** replacing an existing workspace folder with a new one
 		 * ```typescript
-		 * workspace.updateWorkspaceFolders(0, 1, [{ uri: ...}])
+		 * workspace.updateWorkspaceFolders(0, 1, [{ uri: ...}]);
 		 * ```
 		 *
-		 * Note: if the first workspace folder is removed or changed, all extensions will be restarted
+		 * It is valid to remove an existing workspace folder and add it again with a different name
+		 * to rename that folder.
+		 *
+		 * Note: if the first workspace folder is added, removed or changed, all extensions will be restarted
 		 * so that the (deprecated) `rootPath` property is updated to point to the first workspace
 		 * folder.
 		 *
 		 * @param index the zero-based index in the list of currently opened [workspace folders](#WorkspaceFolder)
 		 * from where to delete workspace folders or from where to add to.
 		 * @param deleteCount the optional number of workspace folders to delete from the index that is provided.
-		 * @param workspaceFoldersToAdd the optional number of workspace folders to add
-		 * @return A thenable that resolves when the workspace folder was removed successfully
+		 * @param workspaceFoldersToAdd the optional number of workspace folders to add at the index that is provided.
+		 * @return A thenable that resolves when the workspace folder was removed successfully. The user might prevent
+		 * the operation from happening and this will be indicated with the return type. 
 		 */
 		export function updateWorkspaceFolders(index: number, deleteCount?: number, workspaceFoldersToAdd?: { uri: Uri, name?: string }[]): Thenable<boolean>;
 	}