Add docs

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