docs: Improve documentation and examples for composite keys (#1933)

Also add a deprecated notice to the old `compositeEscape1` and `compositeEscape2` commands
vscode-neovim · May 3, 2024 · c0edf52 · c0edf52
1 parent 8becac6
commit c0edf52
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -172,16 +172,18 @@ reporting it.
 
 ### Composite escape keys
 
-Related configurations:
+#### Configurations
 
 -   `compositeTimeout`
 -   `compositeKeys`
 
-Examples:
+#### Examples
 
-1. <kbd>jj</kbd> to escape
+Add to your `settings.json`:
 
-```json
+-   <kbd>jj</kbd> to escape
+
+```jsonc
 {
     "vscode-neovim.compositeKeys": {
         "jj": {
@@ -191,19 +193,62 @@ Examples:
 }
 ```
 
-2. <kbd>jk</kbd> to escape and save
+-   <kbd>jk</kbd> to escape and save
 
-```json
+```jsonc
 {
     "vscode-neovim.compositeKeys": {
         "jk": {
+            // Use lua to execute any logic
             "command": "vscode-neovim.lua",
-            "args": ["vim.api.nvim_input('<ESC>')\nrequire('vscode-neovim').action('workbench.action.files.save')"]
+            "args": [
+                [
+                    "local code = require('vscode-neovim')",
+                    "code.action('vscode-neovim.escape')",
+                    "code.action('workbench.action.files.save')"
+                ]
+            ]
         }
     }
 }
 ```
 
+#### Migrate from the compositeEscape command
+
+"vscode-neovim.compositeEscape1" and "vscode-neovim.compositeEscape2" commands are deprecated. To migrate:
+
+1. Remove keybindings using `vscode-neovim.compositeEscape` in `keybindings.json`.
+2. Configure `compositeKeys` in `settings.json` to replace the removed keybindings.
+
+<details>
+
+<summary>Example</summary>
+
+If you have the following keybinding in `keybindings.json`:
+
+```json
+{
+    "key": "j",
+    "command": "vscode-neovim.compositeEscape",
+    "when": "neovim.mode == insert && editorTextFocus",
+    "args": "j"
+}
+```
+
+Then you should remove it and add the following configuration to `settings.json`:
+
+```json
+{
+    "vscode-neovim.compositeKeys": {
+        "jj": {
+            "command": "vscode-neovim.escape"
+        }
+    }
+}
+```
+
+</details>
+
 ### Jumplist
 
 VSCode's jumplist is used instead of Neovim's. This is to make VSCode native navigation (mouse click, jump to

diff --git a/src/typing_manager.ts b/src/typing_manager.ts
@@ -63,6 +63,27 @@ export class TypingManager implements Disposable {
     private vscodeDefaultType = (text: string) => commands.executeCommand("default:type", { text });
 
     public constructor(private main: MainController) {
+        // Deprecation warning for old composite escape commands
+        const deprecatedWarning = () => {
+            window
+                .showWarningMessage(
+                    'The command "compositeEscape1" and "compositeEscape2" are deprecated. ',
+                    "Read More",
+                )
+                .then(
+                    (readMore) =>
+                        readMore &&
+                        commands.executeCommand(
+                            "vscode.open",
+                            "https://github.com/vscode-neovim/vscode-neovim/tree/master#composite-escape-keys",
+                        ),
+                );
+        };
+        this.disposables.push(
+            commands.registerCommand("vscode-neovim.compositeEscape1", deprecatedWarning),
+            commands.registerCommand("vscode-neovim.compositeEscape2", deprecatedWarning),
+        );
+
         this.prepareCompositeKeys();
         workspace.onDidChangeConfiguration(this.prepareCompositeKeys, this, this.disposables);