diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index fdcd9f98e13..4325d62d7be 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -2092,8 +2092,10 @@ declare module 'vscode' {
 		/**
 		 * Persisted state from the webview content.
 		 *
-		 * To save resources, VS Code normally deallocates webview views that are not visible. For example, if the user
-		 * collapse a view or switching to another top level activity, the underlying webview document is deallocates.
+		 * To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible.
+		 * For example, when the user collapse a view or switches to another top level activity in the sidebar, the
+		 * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
+		 * the view becomes visible again.
 		 *
 		 * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
 		 * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to