Minor tweaks to syntax reference

docs/test_file_format.md

@@ -1,35 +1,36 @@
 # `scip test` file format
 
-The `scip test` command validates whether a provided SCIP index, matches manually specified fields in a syntax file. These files are loosely based on [Sublime Text's](https://www.sublimetext.com/docs/syntax.html#testing) syntax highlighting tests.
+The `scip test` command validates whether a provided SCIP index contains the data specified in a human-readable test file.
+The test file syntax is inspired by [Sublime Text's syntax highlighting tests](https://www.sublimetext.com/docs/syntax.html#testing).
 
 ## File Format
 
-Test cases are made up of a range, type, and data attribute
+Test cases are made up of a range, type, and data attribute.
 
 ### Ranges
 
 Three range selection comment formats are supported:
 
-- `// ^^^`: enforces the length of the occurrence. Will fail if the range at this location does not equal 3 characters
+- `// ^^^` (2 or more `^`): enforces the length of the occurrence. Will fail if the range at this location does not equal 3 characters
 - `// ^`: ignore length, `^` can occur at any point to any character in the occurrence
 - `// <-`: ignore length, and treat the character above the first comment character as the start of the occurrence, similar to Sublime Text
 
 ```js
 function someFunction() {
   //     ^ ...
-  //    ^^^^^^^^^^^^ ...
+  //     ^^^^^^^^^^^^ ...
   // <- ...
 }
 ```
 
-### Type / Data
+### Type and Data
 
 There are four possible types test cases. The chosen test case is determined by the first word after the range selection
 
 - `definition [symbol]` - validates that the specified range has a symbol with the role of "definition" with the specified `[symbol]`
 - `reference [symbol]` - validates that the specified range has a symbol with the role of "reference" with the specified `[symbol]`
 - `forward_definition [symbol]` - validates that the specified range has a symbol with the role of "forward_definition" with the specified `[symbol]`
-- `diagnostic [value]` - validates that the specified range as a diagnostic with the a value of `[value]`
+- `diagnostic [severity] [message]` - validates that the specified range has a diagnostic with the given `[severity]` and `[message]`
 
 ```js
 function someFunction() {
@@ -40,7 +41,8 @@ function someFunction() {
 }
 ```
 
-Some test types can provide additional data, you can use a `>` character on a new line
+The message for diagnostics can be specified on the following line using `>`,
+and may span over multiple lines.
 
 ```js
 function someFn() {
@@ -49,4 +51,4 @@ function someFn() {
   //   > someVar is unused.
   //   > remove it or use it.
 }
-```
+```