some edits for Variables view contributions

release-notes/v1_49.md

@@ -234,31 +234,43 @@ Note that you cannot publish an extension that uses a proposed API. There may be
 
 ### Contributable context menu for Variables view
 
-It is now possible for extensions to contribute commands to the context menu in the Variables view. More about menu contributions in general can be found in the [API contributions points reference](https://code.visualstudio.com/api/references/contribution-points#contributes.menus).
-
-The Variables context menus have the following default groups, which the extensions can contribute to:
-
-* `navigation`: Commands related to navigation across VS Code. It is empty by default. This group always comes first.
-* `1_view`: Commands related to displaying variables in different view formats. Empty by default.
-* `3_modifications`:  Commands related to modifications of variables. **Set Value** command.
-* `5_cutcopypaste`: Commands related to cutting, copying and pasting of variables. **Copy Value** and **Copy as Expression** commands.
-* `z_commands`: Other commands that do not belong to the above categories. **Add to Watch** and **Break on Value changes** commands. This group comes last.
-
-As the context for these commands, we pass the following object:
-
-```json
-{
-  container: DebugProtocolVariableContainer;
-  variable: DebugProtocolVariable;
-}
-```
-
-`DebugProtocolVariableContainer` is an opaque stand-in type for the intersection of the `Scope` and `Variable` types defined in the Debug Adapter Protocol. A `DebugProtocolVariable` is an opaque stand-in type for the Variable type defined in the Debug Adapter Protocol.
-
-In order to give greater context key flexibility to extensions, we have introduced the following context key: `debugProtocolVariableMenuContext`, which has the value of a `__vscodeVariableMenuContext` attribute from the Variable that the context menu is executed on. This context key should enable extensions, for example, to show array-related commands only on variables that are arrays by passing the `__vscodeVariableMenuContext` attribute with a specific value for those variables.
+We've added command contribution support for the context menu in the Variables view. This makes it possible to implement frequently requested features like variable formatting (e.g. "View as Hex") or viewing variables in custom data views:
 
 ![java variables context menu](./images/1_49/java-variables.png)
 
+When a registered context menu command is executed, both the underlying variable and its container are passed as Debug Adapter Protocol (DAP) objects. Please note that VS Code's extension API uses opaque stand-in types instead of the real DAP types. In order to access their properties, they can be easily coerced into the corresponding DAP types.
+
+Menu contributions for the Variables view are identified by a `"debug/variables/context"` key. General information about menu contributions can be found [here](https://code.visualstudio.com/api/references/contribution-points#contributes.menus).
+
+To help with structuring menu commands into meaningful groups, we have added some predefined groups:
+* `navigation`: Commands related to navigation across VS Code. This group always comes first and is currently empty by default.
+* `1_view`: Commands related to displaying variables in different view formats. Currently empty by default.
+* `3_modifications`:  Commands related to modifications of variables. Currently home of the "Set Value" command.
+* `5_cutcopypaste`: Commands related to cutting, copying and pasting of variables. Currently home of the "Copy Value" and "Copy as Expression" commands.
+* `z_commands`: Other commands that do not belong to the above categories. This group comes last and currently contains the "Add to Watch" and "Break on Value changes" commands.
+
+Typically, menu contributions in the Variables view should only apply to a specific debug type. This can be easily achieved by adding a "when" clause to the contribution. Here is one for Java:
+```js
+"when": "debugConfigurationType == 'java'"
+```
+
+Since some menu contributions should only be available for variables of a specific kind, we have introduced a new optional context key `debugProtocolVariableMenuContext`, which receives its value from a property `__vscodeVariableMenuContext` of the underlying DAP type `Variable` (please note that the `__vscodeVariableMenuContext` property is not part of the DAP specification, because it is specific to VS Code and its menu contribution support).
+
+This makes it possible to show an array related menu command only on variables where a property `__vscodeVariableMenuContext` got a value `'array'` from the debug adapter:
+```js
+  "contributes": {
+    "menus": {
+      "debug/variables/context": [
+        {
+          "command": "variables-view.showArrayAsCustomDataView",
+          "when": "debugConfigurationType == 'java' &&
+                     debugProtocolVariableMenuContext == 'array'"
+        }
+      ]
+    }
+  }
+```
+
 ## Engineering
 
 ### Web Playground moved to a separate repository