fix microsoft#93859

jrieken · jrieken · commit 292fedafa5a6 · 2020-04-07T10:33:37.000+02:00
diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
@@ -2058,18 +2058,25 @@ declare module 'vscode' {
 
 		/**
 		 * Create a new uri which path is the result of joining
-		 * the path of the base uri with the provided path fragments.
+		 * the path of the base uri with the provided path segments.
 		 *
-		 * * Note that `joinPath` only affects the path component
+		 * - Note 1: `joinPath` only affects the path component
 		 * and all other components (scheme, authority, query, and fragment) are
 		 * left as they are.
-		 * * Note that the base uri must have a path; an error is thrown otherwise.
+		 * - Note 2: The base uri must have a path; an error is thrown otherwise.
+		 *
+		 * The path segments are normalized in the following ways:
+		 * - sequences of path separators (`/` or `\`) are replaced with a single separator
+		 * - for `file`-uris on windows, the backslash-character (`\`) is considered a path-separator
+		 * - the `..`-segment denotes the parent segment, the `.` denotes the current segement
+		 * - paths have a root which always remains, for instance on windows drive-letters are roots
+		 * so that is true: `joinPath(Uri.file('file:///c:/root'), '../../other').fsPath === 'c:/other'`
 		 *
 		 * @param base An uri. Must have a path.
-		 * @param pathFragments One more more path fragments
+		 * @param pathSegments One more more path fragments
 		 * @returns A new uri which path is joined with the given fragments
 		 */
-		export function joinPath(base: Uri, ...pathFragments: string[]): Uri;
+		export function joinPath(base: Uri, ...pathSegments: string[]): Uri;
 	}
 
 	//#endregion
