Added documentation for the scope test format (#2818)

Fixes #2815

---------

Co-authored-by: Pokey Rule <[email protected]>

Author: AndreasArvidsson

packages/cursorless-org-docs/src/docs/contributing/adding-a-new-scope.md

@@ -48,6 +48,8 @@ We have a bulk test recorder for scope tests. You can use it by running Cursorle
 
 When you're done, say `"cursorless save scope"` to save the tests to the appropriate files in the `data/fixtures/recorded/scopes` directory.
 
+This step will create partial tests for each of the facets of the given scope. Once you've implemented the scopes in step 5 below, you can automatically update these tests to include the scope ranges, as described in step 6.
+
 ## 5. Add parse tree patterns for the given scope
 
 Launch your extension in debug mode and open a file in your language. You can create one or more files in [`playground/`](../../../../../data/playground) and feel free to include those in your PR.
@@ -61,14 +63,15 @@ Then add parse tree patterns for the given scope to your language's `.scm` file
 - Use the [scope visualizer](../user/scope-visualizer.md) to see your scope highlighted in real time every time you save the `.scm` file.
 - Use the command `"parse tree <target>"` to see the parse tree for a given target. For example `"parse tree line"` will show you the parse tree for the current line, as well as all of its ancestors. This will generate a markdown file with parse tree info, which you can then use to write your patterns. You might find it helpful to open a markdown preview of the file.
 - You will likely want to look at `node-types.json` for your language, (eg [java](https://github.com/tree-sitter/tree-sitter-java/blob/master/src/node-types.json)). This file is generated from the language's `grammar.js`, which might also be helpful to look at (eg [java](https://github.com/tree-sitter/tree-sitter-java/blob/master/grammar.js)).
+- Documentation for the [scope test format](./scope-test-format.md)
 
 ## 6. Update the tests
 
 The tests generated in step 4 only include the code example. Now that you've told Cursorless how to find the scope, we can automatically update the test cases to indicate where the scope should appear in your code examples.
 
 1. Say `"debug edit subset"` and alter the file to include just the name of your language
 2. Run the `Update fixtures subset` launch configuration to update your fixtures.
-3. Check that the fixtures now look as expected, and no other tests for your language have been altered. The VSCode source control side bar is useful for this purpose.
+3. Check that the fixtures now look as expected, and no other tests for your language have been altered. The VSCode source control side bar is useful for this purpose. For help understanding the scope test format, see the [scope test format docs](./scope-test-format.md)
 
 ## 7. File a PR!
 

packages/cursorless-org-docs/src/docs/contributing/parse-tree-patterns.md

@@ -1,4 +1,4 @@
-# Parse tree pattern matcher
+# Parse tree pattern matcher [DEPRECATED]
 
 We have a small domain-specific language that we use to define patterns to look for in tree-sitter parse trees. This DSL enables us to rapidly define new syntactic scope types and support new programming languages.
 

packages/cursorless-org-docs/src/docs/contributing/scope-test-format.md

@@ -0,0 +1,67 @@
+# Scope test format
+
+We have a custom format we use to test that our scopes are correct. The format is automatically generated, so you shouldn't need to edit it yourself. See [Step 6 of the adding a new scope guide](./adding-a-new-scope.md#6-update-the-tests) for more information.
+
+## Example
+
+Example of `.scope` file for the javascript if statement scope.
+
+```
+if (true) {
+
+}
+---
+
+[Content] =
+[Removal] =
+[Domain] = 0:0-2:1
+  >-----------
+0| if (true) {
+1|
+2| }
+   -<
+
+[Insertion delimiter] = "\n"
+```
+
+## Understanding the format
+
+General layout of a `.scope` file is:
+
+```
+Source code
+---
+Scopes
+```
+
+## Source code
+
+The code that you want to generate scopes for. We try to keep this as short and simple as possible while still containing the syntax you want to test.
+
+## Scopes
+
+One or more scopes found in the source code. Each scope is a collection of ranges as well as an insertion delimiter.
+
+A description of the different ranges and how they are used is available in our [glossary](../user/glossary.md).
+
+### Scope ranges
+
+The below example indicates that the content range, removal range, and domain range was the same. Line 0, column 0, to line 2, column 1. These ranges could also be different and in that case each show up as a separate range.
+
+```
+[Content] =
+[Removal] =
+[Domain] = 0:0-2:1
+```
+
+Each range is also visualized:
+
+```
+  >-----------
+0| if (true) {
+1|
+2| }
+   -<
+```
+
+On the left hand side we first have the line numbers, a pipe separator, and finally the source code. The range is visualized by starting after `>` and ending before `<`. Note that `>` and `<` is excluded from the range. That means a range of length one is `>-<` and an empty range is `><`.