diff --git a/src/vs/editor/contrib/codeAction/codeAction.ts b/src/vs/editor/contrib/codeAction/codeAction.ts
index eb0bdba64af..a488d79cae1 100644
--- a/src/vs/editor/contrib/codeAction/codeAction.ts
+++ b/src/vs/editor/contrib/codeAction/codeAction.ts
@@ -32,8 +32,7 @@ export class CodeActionItem {
 	) { }
 
 	async resolve(token: CancellationToken): Promise<this> {
-		// TODO@jrieken when is an item resolved already?
-		if (this.provider?.resolveCodeAction && !this.action.edit && !this.action.command) {
+		if (this.provider?.resolveCodeAction && !this.action.edit) {
 			let action: modes.CodeAction | undefined | null;
 			try {
 				action = await this.provider.resolveCodeAction(this.action, token);
diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index 55e858830d7..8c7e69b22ac 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -19,8 +19,21 @@ declare module 'vscode' {
 	//#region https://github.com/microsoft/vscode/issues/106410
 
 	export interface CodeActionProvider<T extends CodeAction = CodeAction> {
-		// TODO@jrieken make it clear that there is no support for commands, only code action
-		// TODO@jrieken only edit can be set
+
+		/**
+		 * Given a code action fill in its [`edit`](#CodeAction.edit)-property, changes to
+		 * all other properties, like title, are ignored. A code action that has an edit
+		 * will not be resolved.
+		 *
+		 * *Note* that a code action provider that returns commands, not code actions, cannot successfully
+		 * implement this function. Returning commands is deprecated and instead code actions should be
+		 * returned.
+		 *
+		 * @param codeAction A code action.
+		 * @param token A cancellation token.
+		 * @return The resolved code action or a thenable that resolve to such. It is OK to return the given
+		 * `item`. When no result is returned, the given `item` will be used.
+		 */
 		resolveCodeAction?(codeAction: T, token: CancellationToken): ProviderResult<T>;
 	}