Make gc work everywhere, add docs for extensions

Author: ConradIrwin

assets/keymaps/vim.json

@@ -370,7 +370,8 @@
     "bindings": {
       "escape": "vim::ClearOperators",
       "ctrl-c": "vim::ClearOperators",
-      "ctrl-[": "vim::ClearOperators"
+      "ctrl-[": "vim::ClearOperators",
+      "g c": "vim::Comment"
     }
   },
   {
@@ -401,8 +402,7 @@
       "i": "vim::IndentObj",
       "shift-i": ["vim::IndentObj", { "includeBelow": true }],
       "m": "vim::Method",
-      "c": "vim::Class",
-      "g c": "vim::Comment"
+      "c": "vim::Class"
     }
   },
   {

crates/vim/src/object.rs

@@ -1,6 +1,10 @@
 use std::ops::Range;
 
-use crate::{motion::right, state::Mode, Vim};
+use crate::{
+    motion::right,
+    state::{Mode, Operator},
+    Vim,
+};
 use editor::{
     display_map::{DisplaySnapshot, ToDisplayPoint},
     movement::{self, FindRange},
@@ -120,6 +124,9 @@ pub fn register(editor: &mut Editor, cx: &mut ViewContext<Vim>) {
         vim.object(Object::Class, cx)
     });
     Vim::action(editor, cx, |vim, _: &Comment, cx| {
+        if !matches!(vim.active_operator(), Some(Operator::Object { .. })) {
+            vim.push_operator(Operator::Object { around: true }, cx);
+        }
         vim.object(Object::Comment, cx)
     });
     Vim::action(
@@ -276,15 +283,7 @@ impl Object {
                     TextObject::InsideFunction
                 },
             ),
-            Object::Comment => text_object(
-                map,
-                relative_to,
-                if around {
-                    TextObject::AroundComment
-                } else {
-                    TextObject::InsideComment
-                },
-            ),
+            Object::Comment => comment_object(map, relative_to),
             Object::Class => text_object(
                 map,
                 relative_to,
@@ -497,6 +496,16 @@ fn around_next_word(
     Some(start..end)
 }
 
+fn comment_object(
+    map: &DisplaySnapshot,
+    relative_to: DisplayPoint,
+    target: TextObject,
+) -> Option<Range<DisplayPoint>> {
+    let snapshot = &map.buffer_snapshot;
+    let offset = relative_to.to_offset(map, Bias::Left);
+    snapshot.range_for_syntax_ancestor(range)
+}
+
 fn text_object(
     map: &DisplaySnapshot,
     relative_to: DisplayPoint,

docs/src/extensions/languages.md

@@ -69,6 +69,7 @@ several features:
 - Syntax overrides
 - Text redactions
 - Runnable code detection
+- Selecting classes, functions, etc.
 
 The following sections elaborate on how [Tree-sitter queries](https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax) enable these
 features in Zed, using [JSON syntax](https://www.json.org/json-en.html) as a guiding example.
@@ -259,6 +260,45 @@ For example, in JavaScript, we also disable auto-closing of single quotes within
 (comment) @comment.inclusive
 ```
 
+### Text objects
+
+The `textobjects.scm` file defines rules for navigating by text objects. This was added in Zed v0.165 and is currently used only in Vim mode.
+
+Vim provides two levels of granularity for navigating around files. Section-by-section with `[]` etc., and method-by-method with `]m` etc. Even languages that don't support functions and classes can work well by defining similar concepts. For example CSS defines a rule-set as a method, and a media-query as a class.
+
+When there's only one level, use the function matchers instead of class as the `[[` family of motions will fall-back to methods if there are no classes defined. For example, Markdown defines a section as a method so that you can use `[[` to jump to the next heading.
+
+For languages with closures, these typically should not count as functions in Zed. This is best-effort however, as languages like Javascript do not syntactically differentiate syntactically between closures and top-level function declarations.
+
+For languages with declarations like C, provide queries that match `@class.around` or `@function.around`. The `im` and `ic` text objects will default to these if there is no inside.
+
+If you are not sure what to put in textobjects.scm, both [nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects), and the [Helix editor](https://github.com/helix-editor/helix) have queries for many langauges. You can refer to the Zed [built-in languages](https://github.com/zed-industries/zed/tree/main/crates/languages/src) to see how to adapt these.
+
+| Capture          | Description | Vim mode |
+|------------------|-------------|----------|
+| @function.around | An entire function definition or equivalent small section of a file. | `[m`, `]m`, `[M`,`]M` motions.  `am` text object |
+| @function.inside | The function body (the stuff within the braces). | `im` text object |
+| @class.around    | An entire class definition or equivalent large section of a file. | `[[`, `]]`, `[]`, `][` motions. `ac` text object |
+| @class.inside    | The contents of a class definition. | `ic` text object |
+| @comment.around  | An entire comment (e.g. all adjacent line comments, or a block comment) | `gc` text object |
+| @comment.inside  | The contents of a comment | `igc` text object (rarely supported) |
+
+For example:
+```scheme
+; include only the content of the method in the function
+(method_definition
+    body: (_
+        "{"
+        (_)* @function.inside
+        "}")) @function.around
+
+; match function.around for declarations with no body
+(function_signature_item) @function.around
+
+; join all adjacent comments into one
+(comment)+ @comment.around
+```
+
 ### Text redactions
 
 The `redactions.scm` file defines text redaction rules. When collaborating and sharing your screen, it makes sure that certain syntax nodes are rendered in a redacted mode to avoid them from leaking.