diff --git a/src/vscode-dts/vscode.proposed.textEditorDrop.d.ts b/src/vscode-dts/vscode.proposed.textEditorDrop.d.ts
index 35a712c749c..f0ea3649a82 100644
--- a/src/vscode-dts/vscode.proposed.textEditorDrop.d.ts
+++ b/src/vscode-dts/vscode.proposed.textEditorDrop.d.ts
@@ -13,11 +13,35 @@ declare module 'vscode' {
 		constructor(range: Range, snippet: SnippetString);
 	}
 
+	/**
+	 * Provider which handles dropping of resources into a text editor.
+	 *
+	 * The user can drop into a text editor by holding down `shift` while dragging. Requires `workbench.editor.dropIntoEditor.enabled` to be on.
+	 */
 	export interface DocumentOnDropProvider {
+		/**
+		 * Provide edits which inserts the content being dragged and dropped into the document.
+		 *
+		 * @param document The document in which the drop occurred.
+		 * @param position The position in the document where the drop occurred.
+		 * @param dataTransfer A {@link DataTransfer} object that holds data about what is being dragged and dropped.
+		 * @param token A cancellation token.
+		 *
+		 * @return A {@link SnippetTextEdit} or a thenable that resolves to such. The lack of a result can be
+		 * signaled by returning `undefined` or `null`.
+		 */
 		provideDocumentOnDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<SnippetTextEdit>;
 	}
 
 	export namespace languages {
+		/**
+		 * Registers a new {@link DocumentOnDropProvider}.
+		 *
+		 * @param selector A selector that defines the documents this provider applies to.
+		 * @param provider A drop provider.
+		 *
+		 * @return A {@link Disposable} that unregisters this provider when disposed of.
+		 */
 		export function registerDocumentOnDropProvider(selector: DocumentSelector, provider: DocumentOnDropProvider): Disposable;
 	}
 }