From 1ecce5d1a6819696b5187de1d69867cfcd8da306 Mon Sep 17 00:00:00 2001
From: Mark Spanbroek <mark@spanbroek.net>
Date: Tue, 1 Mar 2022 09:25:15 +0100
Subject: [PATCH] Update documentation for setupAll and teardownAll

---
 Readme.md               | 19 +++++++++++--------
 asynctest/templates.nim |  4 ++--
 2 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/Readme.md b/Readme.md
index d783b88..b7691d9 100644
--- a/Readme.md
+++ b/Readme.md
@@ -33,14 +33,6 @@ proc someAsyncProc {.async.} =
 
 suite "test async proc":
 
-  setupAll:
-    # invoke await in the suite setup:
-    await someAsyncProc()
-
-  teardownAll:
-    # invoke await in the suite teardown:
-    await someAsyncProc()
-
   setup:
     # invoke await in each test setup:
     await someAsyncProc()
@@ -55,6 +47,17 @@ suite "test async proc":
 
 ```
 
+setupAll and teardownAll
+------------------------
+
+The `setup` and `teardown` code runs before and after every test, just like the
+standard [unittest][1] module. In addition we provide `setupAll` and
+`teardownAll`. The `setupAll` code runs once before all tests in the suite, and
+the `teardownAll` runs once after all tests in the suite. Use these only as a
+last resort when setting up the test environment is very costly. Be careful that
+the tests do not modify the environment that you set up, lest you introduce
+dependencies between tests.
+
 Unittest2
 ---------
 
diff --git a/asynctest/templates.nim b/asynctest/templates.nim
index af575a7..4bd0f0a 100644
--- a/asynctest/templates.nim
+++ b/asynctest/templates.nim
@@ -2,12 +2,12 @@ template suite*(name, body) =
 
   suite name:
 
-    # Runs before all tests in the suite
+    ## Runs before all tests in the suite
     template setupAll(setupAllBody) {.used.} =
       let b = proc {.async.} = setupAllBody
       waitFor b()
 
-    # Runs after all tests in the suite
+    ## Runs after all tests in the suite
     template teardownAll(teardownAllBody) {.used.} =
       template teardownAllIMPL: untyped {.inject.} =
         let a = proc {.async.} = teardownAllBody