some jsdoc for #1800

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>;
 	}