From 1f319a70ce82a15e656b004e914d2e297ee976b2 Mon Sep 17 00:00:00 2001
From: Michael Miller <icy.arctic.fox@gmail.com>
Date: Sat, 7 Nov 2020 22:04:21 -0700
Subject: [PATCH] Add docs

---
 src/spectator/dsl/examples.cr | 43 ++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/spectator/dsl/examples.cr b/src/spectator/dsl/examples.cr
index e245f79..7b246bc 100644
--- a/src/spectator/dsl/examples.cr
+++ b/src/spectator/dsl/examples.cr
@@ -2,12 +2,17 @@ require "../source"
 require "./builder"
 
 module Spectator::DSL
+  # DSL methods for defining examples and test code.
   module Examples
+    # Defines a macro to generate code for an example.
+    # The *name* is the name given to the macro.
+    # TODO: Mark example as pending if block is omitted.
     macro define_example(name)
       macro {{name.id}}(what = nil, &block)
         \{% raise "Cannot use '{{name.id}}' inside of a test block" if @def %}
+        \{% raise "A description or block must be provided. Cannot use '{{name.id}}' alone." unless what || block %}
 
-        def \%test
+        def \%test # TODO: Pass example instance.
           \{{block.body}}
         end
 
@@ -33,10 +38,46 @@ module Spectator::DSL
       {% end %}
     end
 
+    # Defines an example.
+    #
+    # If a block is given, it is treated as the code to test.
+    # The block is provided the current example instance as an argument.
+    #
+    # The first argument names the example (test).
+    # Typically, this specifies what is being tested.
+    # It has no effect on the test and is purely used for output.
+    # If omitted, a name is generated from the first assertion in the test.
+    #
+    # The example will be marked as pending if the block is omitted.
+    # A block or name must be provided.
     define_example :example
 
+    # Defines an example.
+    #
+    # If a block is given, it is treated as the code to test.
+    # The block is provided the current example instance as an argument.
+    #
+    # The first argument names the example (test).
+    # Typically, this specifies what is being tested.
+    # It has no effect on the test and is purely used for output.
+    # If omitted, a name is generated from the first assertion in the test.
+    #
+    # The example will be marked as pending if the block is omitted.
+    # A block or name must be provided.
     define_example :it
 
+    # Defines an example.
+    #
+    # If a block is given, it is treated as the code to test.
+    # The block is provided the current example instance as an argument.
+    #
+    # The first argument names the example (test).
+    # Typically, this specifies what is being tested.
+    # It has no effect on the test and is purely used for output.
+    # If omitted, a name is generated from the first assertion in the test.
+    #
+    # The example will be marked as pending if the block is omitted.
+    # A block or name must be provided.
     define_example :specify
   end