Initial cleanup and docs for FailureBlock

src/spectator/formatters/failure_block.cr

@@ -1,17 +1,34 @@
 module Spectator::Formatters
+  # Constructs a block of text containing information about a failed example.
+  #
+  # A failure block takes the form:
+  #
+  # ```text
+  #   1) Example name
+  #      Failure: Reason or message
+  #
+  #      Expected: value
+  #           got: value
+  #
+  #  # spec/source_spec.cr:42
+  # ```
   class FailureBlock
+    # Creates the failure block.
+    # The `index` uniquely identifies the failure in the output.
+    # The `result` is the outcome of the failed example.
     def initialize(@index : Int32, @result : FailedResult)
     end
 
-
+    # Creates the block of text describing the failure.
     def to_s(io)
-      to_s_title(io)
+      title(io)
-      to_s_message(io)
+      message(io)
-      to_s_expected_actual(io)
+      values(io)
-      to_s_source(io)
+      source(io)
     end
 
-    private def to_s_title(io)
+    # Produces the title of the failure block.
+    private def title(io)
       io << "  "
       io << @index
       io << ')'
@@ -19,22 +36,25 @@ module Spectator::Formatters
       io.puts
     end
 
-    private def to_s_message(io)
+    # Produces the message line of the failure block.
+    private def message(io)
       io << "     Failure: "
       io << @result.error
       io.puts
     end
 
-    private def to_s_expected_actual(io)
+    # Produces the values list of the failure block.
+    private def values(io)
       io.puts
       io.puts "       Expected: TODO"
       io.puts "            got: TODO"
       io.puts
     end
 
-    private def to_s_source(io)
+    # Produces the source line of the failure block.
+    private def source(io)
       io << "     # "
-      source(io)
+      @result.example.source.to_s(io)
     end
   end
 end