diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index 4fce9d49e50..7da978be049 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -19,10 +19,18 @@ declare module 'vscode' {
 	//#region Joh - vscode.open
 
 	export namespace env {
+
 		/**
+		 * Opens an *external* item, e.g. a http(s) or mailto-link, using the
+		 * default application.
 		 *
+		 * *Note* that [`showTextDocument`](#window.showTextDocument) is the right
+		 * way to open a text document inside the editor, not this function.
+		 *
+		 * @param target The uri that should be opened.
+		 * @returns A promise indicating if open was successful.
 		 */
-		export function open(uri: Uri): Thenable<boolean>;
+		export function open(target: Uri): Thenable<boolean>;
 	}
 
 	//#endregion