diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index af1b501c6bb08bbe3642052ae00967917bdd5c3d..85d90e939d6794964c9cebf05647e53cfce843dc 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -16,7 +16,15 @@ declare module 'vscode' {
 	export namespace languages {
 
 		/**
+		 * Set (and change) the [language](#TextDocument.languageId) that is associated
+		 * with the given document.
 		 *
+		 * *Note* that calling this function will trigger the [`onDidCloseTextDocument`](#languages.onDidCloseTextDocument) event
+		 * followed by the [`onDidOpenTextDocument`](#languages.onDidOpenTextDocument) event.
+		 *
+		 * @param document The document which language is to be changed
+		 * @param languageId The new language identifier.
+		 * @returns A thenable that resolves with the updated document.
 		 */
 		export function setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument>;
 	}