diff --git a/src/vs/vscode.d.ts b/src/vs/vscode.d.ts
index 207183cb8d8..cbf69745888 100644
--- a/src/vs/vscode.d.ts
+++ b/src/vs/vscode.d.ts
@@ -2495,16 +2495,18 @@ declare module 'vscode' {
 
 	/**
 	 * The evaluatable expression provider interface defines the contract between extensions and
-	 * the debug hover.
+	 * the debug hover. In this contract the provider returns an evaluatable expression for a given position
+	 * in a document and VS Code evaluates this expression in the active debug session and shows the result in a debug hover.
 	 */
 	export interface EvaluatableExpressionProvider {
 
 		/**
 		 * Provide an evaluatable expression for the given document and position.
+		 * VS Code will evaluate this expression in the active debug session and will show the result in the debug hover.
 		 * The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression.
 		 *
-		 * @param document The document in which the debug hover is opened.
-		 * @param position The position in the document where the debug hover is opened.
+		 * @param document The document for which the debug hover is about to appear.
+		 * @param position The line and character position in the document where the debug hover is about to appear.
 		 * @param token A cancellation token.
 		 * @return An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be
 		 * signaled by returning `undefined` or `null`.
@@ -9174,6 +9176,7 @@ declare module 'vscode' {
 
 		/**
 		 * Register a provider that locates evaluatable expressions in text documents.
+		 * VS Code will evaluate the expression in the active debug session and will show the result in the debug hover.
 		 *
 		 * If multiple providers are registered for a language an arbitrary provider will be used.
 		 *