Improve documentation of test format

test-data/unit/README.md

@@ -29,12 +29,23 @@ Add the test in this format anywhere in the file:
 - `# E: abc...` indicates that this line should result in type check error
 with text "abc..."
 - note a space after `E:` and `flags:`
-- `# E:12` adds column number to the expected error
-- use `\` to escape the `#` character and indicate that the rest of the line is part of
-the error message
-- repeating `# E: ` several times in one line indicates multiple expected errors in one line
-- `W: ...` and `N: ...` works exactly like `E: ...`, but report a warning and a note respectively
+- `# E:12` adds column number to the expected error. Example: `# E:12: ...`.
+- ` # ` will terminate the error message that comes before it;
+  this allows for multiple comments on the same line. Example: `# E: ... # This type fails`.
+  Use `\` to escape a `#` character to include it in the error message. Example:
+  `# E: This error message includes the \# character once # new comment`.
+  Note that there is no support by the test file format for using `\\` to escape a backslash;
+  the sequence `\\#` is interpreted as `\` followed by an escaped `#`, and `\\\#` as
+  two `\` followed by an escaped `#`.
+  Note also: in all other contexts, such as line-continuation, the backslash acts
+  as it normally would in a Python source file.
+- repeating ` # E: ` several times in one line indicates multiple expected errors in one line
+- `W: ...` and `N: ...` work exactly like `E: ...`, but report a warning and a note respectively
 - lines that don't contain the above should cause no type check errors
+- lines that begin with `--` are test-file-format comments, and will not appear in the tested python
+  source code
+- some test files are run in a special way by the test runner; this is typically documented in
+  test-file-format comments at the top of the test file
 - optional `[builtins fixtures/...]` tells the type checker to use
 `builtins` stubs from the indicated file (see Fixtures section below)
 - optional `[out]` is an alternative to the `# E: ` notation: it indicates that
@@ -45,6 +56,8 @@ the test without having to change line numbers in `[out]`
 - an empty `[out]` section has no effect
 - to add tests for a feature that hasn't been implemented yet, append `-xfail`
   to the end of the test name
+- to mark a test as to-be-skipped, append `-skip`. For more on the distinction
+  between xfail and skip, see https://docs.pytest.org/en/stable/how-to/skipping.html
 - to run just this test, use `pytest -n0 -k testNewSyntaxBasics`