Explain inline tests

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 0330939b6..cf93135ee 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -303,6 +303,17 @@ Rather than talking in definitions and references, it talks in Strings and textu
 In general, API is centered around UI concerns -- the result of the call is what the user sees in the editor, and not what the compiler sees underneath.
 The results are 100% Rust specific though.
 
+## Parser Tests
+
+Test for parser (`ra_parser`) live in `ra_syntax` crate (see `test_data` direcotory).
+There are two kinds of tests:
+
+* Manually written test cases in `parser/ok` and `parser/error`
+* "Inline" tests in `parser/inline` (these are generated) from comments in `ra_parser` crate.
+
+The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
+If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to