From 6c8ec7953a00cb07f3644bed221fb652fb49b1cc Mon Sep 17 00:00:00 2001
From: Michael Miller <icy.arctic.fox@gmail.com>
Date: Thu, 17 Jan 2019 16:02:29 -0700
Subject: [PATCH] Add note about using pre- and post-conditions

---
 src/spectator/dsl/structure_dsl.cr | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/spectator/dsl/structure_dsl.cr b/src/spectator/dsl/structure_dsl.cr
index 71af696..17e1d21 100644
--- a/src/spectator/dsl/structure_dsl.cr
+++ b/src/spectator/dsl/structure_dsl.cr
@@ -912,6 +912,10 @@ module Spectator::DSL
     # end
     # ```
     #
+    # NOTE: Pre-conditions should not be checked in a `#before_all` or related block.
+    # Errors that occur in a `#before_all` block will halt testing and abort with an error.
+    # Use `#pre_condition` instead for pre-test checks.
+    #
     # See also: `#before_each`, `#after_all`, `#after_each`, and `#around_each`.
     macro before_all(&block)
       ::Spectator::DSL::Builder.add_before_all_hook {{block}}
@@ -963,6 +967,10 @@ module Spectator::DSL
     # end
     # ```
     #
+    # NOTE: Pre-conditions should not be checked in a `#before_each` or related block.
+    # Errors that occur in a `#before_each` block will halt testing and abort with an error.
+    # Use `#pre_condition` instead for pre-test checks.
+    #
     # See also: `#before_all`, `#after_all`, `#after_each`, and `#around_each`.
     macro before_each(&block)
       # Before each hook.
@@ -1024,6 +1032,10 @@ module Spectator::DSL
     # end
     # ```
     #
+    # NOTE: Post-conditions should not be checked in an `#after_all` or related block.
+    # Errors that occur in an `#after_all` block will halt testing and abort with an error.
+    # Use `#post_condition` instead for post-test checks.
+    #
     # See also: `#before_all`, `#before_each`, `#after_each`, and `#around_each`.
     macro after_all(&block)
       ::Spectator::DSL::Builder.add_after_all_hook {{block}}
@@ -1074,6 +1086,10 @@ module Spectator::DSL
     # end
     # ```
     #
+    # NOTE: Post-conditions should not be checked in an `#after_each` or related block.
+    # Errors that occur in an `#after_each` block will halt testing and abort with an error.
+    # Use `#post_condition` instead for post-test checks.
+    #
     # See also: `#before_all`, `#before_each`, `#after_all`, and `#around_each`.
     macro after_each(&block)
       # After each hook.
@@ -1166,6 +1182,10 @@ module Spectator::DSL
     # end
     # ```
     #
+    # NOTE: Pre- and post-conditions should not be checked in an `#around_each` or similar block.
+    # Errors that occur in an `#around_each` block will halt testing and abort with an error.
+    # Use `#pre_condition` and `#post_condition` instead for pre- and post-test checks.
+    #
     # See also: `#before_all`, `#before_each`, `#after_all`, and `#after_each`.
     macro around_each(&block)
       # Around each hook.