[DOCS] Document // TEARDOWN test snippet.
The `// TEARDOWN` test snippet was added with You can use this
snippet to end and clean up a test series started with `// TESTSETUP` or
`// TEST[setup:name]`.
@@ -31,6 +31,8 @@ for its modifiers:
This is most useful when you have text and snippets that work together to
tell the story of some use case because it merges the snippets (and thus the
use case) into one big test.
+ * You can't use `// TEST[continued]` immediately after `// TESTSETUP` or
+ `// TEARDOWN`.
* `// TEST[skip:reason]`: Skip this test. Replace `reason` with the actual
reason to skip the test. Snippets without `// TEST` or `// CONSOLE` aren't
considered tests anyway but this is useful for explicitly documenting the
@@ -76,7 +78,11 @@ for its modifiers:
but rather than the setup defined in `docs/build.gradle` the setup is defined
right in the documentation file. In general, we should prefer `// TESTSETUP`
over `// TEST[setup:name]` because it makes it more clear what steps have to
- be taken before the examples will work.
+ be taken before the examples will work. Tip: `// TESTSETUP` can only be used
+ on the first snippet of a document.
+* `// TEARDOWN`: Ends and cleans up a test series started with `// TESTSETUP` or
+ `// TEST[setup:name]`. You can use `// TEARDOWN` to set up multiple tests in
+ the same file.
* `// NOTCONSOLE`: Marks this snippet as neither `// CONSOLE` nor
`// TESTRESPONSE`, excluding it from the list of unconverted snippets. We
should only use this for snippets that *are* JSON but are *not* responses or
