encoding - api clarification (#245994)

b8965e8d · Benjamin Pasero · GitHub · 599b974c · b8965e8d · b8965e8d
--- a/extensions/vscode-api-tests/src/singlefolder-tests/workspace.test.ts
+++ b/extensions/vscode-api-tests/src/singlefolder-tests/workspace.test.ts
@@ -1380,6 +1380,13 @@ suite('vscode API - workspace', () => {
 		assert.ok(err);
 	});

+	test('encoding: openTextDocument - invalid encoding falls back to default', async () => {
+		const uri1 = await createRandomFile();
+
+		const doc1 = await vscode.workspace.openTextDocument(uri1, { encoding: 'foobar123' });
+		assert.strictEqual(doc1.encoding, 'utf8');
+	});
+
 	test('encoding: openTextDocument - multiple requests with different encoding work', async () => {
 		const uri1 = await createRandomFile();


--- a/src/vscode-dts/vscode.proposed.textDocumentEncoding.d.ts
+++ b/src/vscode-dts/vscode.proposed.textDocumentEncoding.d.ts
@@ -60,7 +60,8 @@ declare module 'vscode' {
 			 * unless the document is already opened.
 			 *
 			 * See {@link TextDocument.encoding} for more information about valid
-			 * values for encoding.
+			 * values for encoding. Using an invalid encoding will fallback to the
+			 * default encoding for the document.
 			 *
 			 * *Note* that opening a text document that was already opened with a
 			 * different encoding has the potential of changing the text contents of
@@ -90,7 +91,8 @@ declare module 'vscode' {
 			 * unless the document is already opened.
 			 *
 			 * See {@link TextDocument.encoding} for more information about valid
-			 * values for encoding.
+			 * values for encoding. Using an invalid encoding will fallback to the
+			 * default encoding for the document.
 			 *
 			 * *Note* that opening a text document that was already opened with a
 			 * different encoding has the potential of changing the text contents of
@@ -123,6 +125,10 @@ declare module 'vscode' {
 			content?: string;
 			/**
 			 * The {@link TextDocument.encoding encoding} of the document.
+			 *
+			 * See {@link TextDocument.encoding} for more information about valid
+			 * values for encoding. Using an invalid encoding will fallback to the
+			 * default encoding for the document.
 			 */
 			encoding?: string;
 		}): Thenable<TextDocument>;
@@ -147,7 +153,8 @@ declare module 'vscode' {
 		 * @param uri The URI that represents the file. This information
 		 * is used to figure out the encoding related configuration for the file.
 		 * @param options Allows to explicitly pick the encoding to use. See {@link TextDocument.encoding}
-		 * for more information about valid values for encoding.
+		 * for more information about valid values for encoding. Using an invalid encoding will fallback
+		 * to the default encoding for the document.
 		 * @returns A thenable that resolves to the decoded `string`.
 		 */
 		export function decode(content: Uint8Array, uri: Uri | undefined, options?: { encoding: string }): Thenable<string>;
@@ -162,7 +169,8 @@ declare module 'vscode' {
 		 * @param uri The URI that represents the file. This information
 		 * is used to figure out the encoding related configuration for the file.
 		 * @param options Allows to explicitly pick the encoding to use. See {@link TextDocument.encoding}
-		 * for more information about valid values for encoding.
+		 * for more information about valid values for encoding. Using an invalid encoding will fallback
+		 * to the default encoding for the document.
 		 * @returns A thenable that resolves to the encoded `Uint8Array`.
 		 */
 		export function encode(content: string, uri: Uri | undefined, options?: { encoding: string }): Thenable<Uint8Array>;