Merge #4835

4835: Explain inline tests r=matklad a=matklad



bors r+
🤖

Co-authored-by: Aleksey Kladov <aleksey.kladov@gmail.com>

Author: bors[bot]

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