add guidance for setExpression; fixes #188

changelog.md

@@ -6,6 +6,9 @@ sectionid: changelog
 
 #### All notable changes to the specification will be documented in this file.
 
+* 1.48.x:
+  * Add guidance for the case that a debug adapter implements both `setVariable` and `setExpression` and clients need to decide which request to use.
+
 * 1.47.x:
   * The `setExceptionBreakpoints` can now optionally return an array of `Breakpoint`s as the other `setXxxxBreakpoints` do. This allows clients to show validation error messages for individual exception breakpoints or filters.
   * The `restart` request got a new optional parameter `arguments` where a client can pass the latest version of a launch or attach configuration.

debugAdapterProtocol.json

@@ -2020,7 +2020,7 @@
 		"SetVariableRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
-				"description": "Set the variable with the given name in the variable container to a new value. Clients should only call this request if the capability 'supportsSetVariable' is true.",
+				"description": "Set the variable with the given name in the variable container to a new value. Clients should only call this request if the capability 'supportsSetVariable' is true.\nIf a debug adapter implements both setVariable and setExpression, a client will only use setExpression if the variable has an evaluateName property.",
 				"properties": {
 					"command": {
 						"type": "string",
@@ -2412,7 +2412,7 @@
 		"SetExpressionRequest": {
 			"allOf": [ { "$ref": "#/definitions/Request" }, {
 				"type": "object",
-				"description": "Evaluates the given 'value' expression and assigns it to the 'expression' which must be a modifiable l-value.\nThe expressions have access to any variables and arguments that are in scope of the specified frame.\nClients should only call this request if the capability 'supportsSetExpression' is true.",
+				"description": "Evaluates the given 'value' expression and assigns it to the 'expression' which must be a modifiable l-value.\nThe expressions have access to any variables and arguments that are in scope of the specified frame.\nClients should only call this request if the capability 'supportsSetExpression' is true.\nIf a debug adapter implements both setExpression and setVariable, a client will only use setExpression if the variable has an evaluateName property.",
 				"properties": {
 					"command": {
 						"type": "string",

specification.md

@@ -2128,6 +2128,8 @@ interface VariablesResponse extends Response {
 
 Set the variable with the given name in the variable container to a new value. Clients should only call this request if the capability 'supportsSetVariable' is true.
 
+If a debug adapter implements both setVariable and setExpression, a client will only use setExpression if the variable has an evaluateName property.
+
 ```typescript
 interface SetVariableRequest extends Request {
   command: 'setVariable';
@@ -2526,6 +2528,8 @@ The expressions have access to any variables and arguments that are in scope of
 
 Clients should only call this request if the capability 'supportsSetExpression' is true.
 
+If a debug adapter implements both setExpression and setVariable, a client will only use setExpression if the variable has an evaluateName property.
+
 ```typescript
 interface SetExpressionRequest extends Request {
   command: 'setExpression';