Add docs for result types

src/spectator/errored_result.cr

@@ -1,9 +1,13 @@
 require "./failed_result"
 
 module Spectator
+  # Outcome that indicates running an example generated an error.
+  # This type of result occurs when an exception was raised.
+  # This is different from a "failed" result
+  # in that the error was not from a failed expectation.
   class ErroredResult < FailedResult
-    getter error : Exception
-
+    # Indicates whether an error was encountered while running the example.
+    # This will always be true for this type of result.
     def errored?
       true
     end

src/spectator/failed_result.cr

@@ -1,26 +1,46 @@
 require "./result"
 
 module Spectator
+  # Outcome that indicates running an example was a failure.
   class FailedResult < Result
+    # Error that occurred while running the example.
     getter error : Exception
+
+    # The expectations that were run in the example.
     getter expectations : Expectations::ExampleExpectations
 
+    # Creates a failed result.
+    # The `example` should refer to the example that was run
+    # and that this result is for.
+    # The `elapsed` argument is the length of time it took to run the example.
+    # The `expectations` references the expectations that were checked in the example.
+    # The `error` is the exception that was raised to cause the failure.
     def initialize(example, elapsed, @expectations, @error)
       super(example, elapsed)
     end
 
+    # Indicates that an example was run and it was successful.
+    # NOTE: Examples with warnings count as successful.
+    # This will always be false for this type of result.
     def passed?
       false
     end
 
+    # Indicates that an example was run, but it failed.
+    # Errors count as failures.
+    # This will always be true for this type of result.
     def failed?
       true
     end
 
+    # Indicates whether an error was encountered while running the example.
+    # This will always be false for this type of result.
     def errored?
       false
     end
 
+    # Indicates that an example was marked as pending.
+    # This will always be false for this type of result.
     def pending?
       false
     end

src/spectator/pending_result.cr

@@ -1,25 +1,41 @@
 require "./result"
 
 module Spectator
+  # Outcome that indicates running an example was pending.
+  # A pending result means the example is not ready to run yet.
+  # This can happen when the functionality to be tested is not implemented yet.
   class PendingResult < Result
+    # Creates a pending result.
+    # The `example` should refer to the example that was run
+    # and that this result is for.
+    def initialize(example)
+      super(example, Time::Span.zero)
+    end
+
+    # Indicates that an example was run and it was successful.
+    # NOTE: Examples with warnings count as successful.
+    # This will always be false for this type of result.
     def passed?
       false
     end
 
+    # Indicates that an example was run, but it failed.
+    # Errors count as failures.
+    # This will always be false for this type of result.
     def failed?
       false
     end
 
+    # Indicates whether an error was encountered while running the example.
+    # This will always be false for this type of result.
     def errored?
       false
     end
 
+    # Indicates that an example was marked as pending.
+    # This will always be true for this type of result.
     def pending?
       true
     end
-
-    def initialize(@example)
-      super(@example, Time::Span.zero)
-    end
   end
 end

src/spectator/result.cr

@@ -1,14 +1,32 @@
 module Spectator
+  # Base class that represents the outcome of running an example.
+  # Sub-classes contain additional information specific to the type of result.
   abstract class Result
+    # Example that was run that this result is for.
     getter example : Example
+
+    # Length of time it took to run the example.
     getter elapsed : Time::Span
 
+    # Indicates that an example was run and it was successful.
+    # NOTE: Examples with warnings count as successful.
     abstract def passed? : Bool
+
+    # Indicates that an example was run, but it failed.
+    # Errors count as failures.
     abstract def failed? : Bool
+
+    # Indicates whether an error was encountered while running the example.
     abstract def errored? : Bool
+
+    # Indicates that an example was marked as pending.
     abstract def pending? : Bool
 
-    protected def initialize(@example, @elapsed)
+    # Constructs the base of the result.
+    # The `example` should refer to the example that was run
+    # and that this result is for.
+    # The `elapsed` argument is the length of time it took to run the example.
+    private def initialize(@example, @elapsed)
     end
   end
 end

src/spectator/successful_result.cr

@@ -1,25 +1,42 @@
 require "./result"
 
 module Spectator
+  # Outcome that indicates running an example was successful.
   class SuccessfulResult < Result
+    # The expectations that were run in the example.
     getter expectations : Expectations::ExampleExpectations
 
+    # Creates a successful result.
+    # The `example` should refer to the example that was run
+    # and that this result is for.
+    # The `elapsed` argument is the length of time it took to run the example.
+    # The `expectations` references the expectations that were checked in the example.
     def initialize(example, elapsed, @expectations)
       super(example, elapsed)
     end
 
+    # Indicates that an example was run and it was successful.
+    # NOTE: Examples with warnings count as successful.
+    # This will always be true for this type of result.
     def passed?
       true
     end
 
+    # Indicates that an example was run, but it failed.
+    # Errors count as failures.
+    # This will always be false for this type of result.
     def failed?
       false
     end
 
+    # Indicates whether an error was encountered while running the example.
+    # This will always be false for this type of result.
     def errored?
       false
     end
 
+    # Indicates that an example was marked as pending.
+    # This will always be false for this type of result.
     def pending?
       false
     end