2 files changed, 23 insertions, 3 deletions

diff --git a/docs/TESTS.md b/docs/TESTS.md
index 8005ec9da..db06dbebc 100644
--- a/docs/TESTS.md
+++ b/docs/TESTS.md
@@ -19,12 +19,26 @@ files to have the same name except for the leading number. In general,
 test suite should be append-only: old tests should not be modified,
 new tests should be created instead.
 
-
 Note that only `ok` tests are normative: `err` tests test error
 recovery and it is totally ok for a parser to not implement any error
 recovery at all. However, for libsyntax2.0 we do care about error
 recovery, and we do care about precise and useful error messages.
 
+There are also so-called "inline tests". They appear as the comments 
+with a `test` header in the source code, like this:
+
+```rust
+// test fn_basic
+// fn foo() {}
+fn fn_item(p: &mut Parser) {
+    // ...
+}
+``` 
+
+You can run `cargo collect-tests` command to collect all inline tests 
+into `tests/data/inline` directory. The main advantage of inline tests
+is that they help to illustrate what the relevant code is doing. 
+
 
 Contribution opportunity: design and implement testing infrastructure
 for validators.
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
index 1fcfa2dec..f8754c06f 100644
--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -17,14 +17,20 @@ cargo tool
 ```
 
 
-# Tool: `gen`
+## Tool: `gen`
 
 This tool reads a "grammar" from [grammar.ron](../grammar.ron) and
 generates the `syntax_kinds.rs` file. You should run this tool if you 
 add new keywords or syntax elements.
 
 
-# Tool: 'parse'
+## Tool: `parse`
 
 This tool reads rust source code from the standard input, parses it,
 and prints the result to stdout.
+
+
+## Tool: `collect-tests`
+
+This tools collect inline tests from comments in libsyntax2 source code
+and places them into `tests/data/inline` directory.