diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index c4ec6306a2565158a89a330b78eae729d3045a45..6e1ea7f6d9fe14ce08e7c4cac4bf623c1b6c1c5a 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -351,11 +351,12 @@ declare module 'vscode' {
 	}
 
 	/**
-	 * A data provider that provides tree data for a view
+	 * A data provider that provides tree data
 	 */
 	export interface TreeDataProvider<T> {
 		/**
 		 * An optional event to signal that an element or root has changed.
+		 * To signal that root has changed, do not pass any argument or pass `undefined` or `null`.
 		 */
 		onDidChangeTreeData?: Event<T | undefined | null>;
 
@@ -368,10 +369,10 @@ declare module 'vscode' {
 		getTreeItem(element: T): TreeItem | Thenable<TreeItem>;
 
 		/**
-		 * Get the children of `element` or root if no element (`undefined`) is passed.
+		 * Get the children of `element` or root if no element is passed.
 		 *
 		 * @param element The element from which the provider gets children. Can be `undefined`.
-		 * @return Children of `element` or root if no element (`undefined`) is passed.
+		 * @return Children of `element` or root if no element is passed.
 		 */
 		getChildren(element?: T): ProviderResult<T[]>;
 	}