Documentation for expectations and matchers

src/spectator/expectations/expectation.cr

@@ -2,6 +2,8 @@ module Spectator::Expectations
   # Min-in for all expectation types.
   # Classes that include this must implement
   # the `#satisfied?`, `#message`, and `#negated_message` methods.
+  # Typically, expectation classes/structs store an `ExpectationPartial`
+  # and a `Matchers::Matcher` and then proxy calls to those instances.
   module Expectation
     # Checks whether the expectation is met.
     abstract def satisfied? : Bool

src/spectator/expectations/expectation_partial.cr

@@ -4,6 +4,8 @@ module Spectator::Expectations
   # The part of the expectation this class covers is the actual value.
   # This can also cover a block's behavior.
   # Sub-types of this class are returned by the `DSL::ExampleDSL.expect` call.
+  # Sub-types are expected to implement their own variation
+  # of the `#to` and `#not_to` methods.
   abstract struct ExpectationPartial
     # User-friendly string displayed for the actual expression being tested.
     # For instance, in the expectation:

src/spectator/expectations/value_expectation.cr

@@ -1,9 +1,15 @@
 require "./expectation"
 
 module Spectator::Expectations
+  # Expectation that operates on values.
+  # There are two values - the actual and expected.
+  # The actual value is what the SUT returned.
+  # The expected value is what the test wants to see.
   struct ValueExpectation(ActualType, ExpectedType)
     include Expectation
 
+    # Creates the expectation.
+    # This simply takes in the expectation partial and the matcher.
     def initialize(@partial : ValueExpectationPartial(ActualType),
                    @matcher : Matchers::ValueMatcher(ExpectedType))
     end

src/spectator/expectations/value_expectation_partial.cr

@@ -1,19 +1,27 @@
 require "./expectation_partial"
 
 module Spectator::Expectations
+  # Expectation partial variation that operates on a value.
   struct ValueExpectationPartial(ActualType) < ExpectationPartial
+    # Actual value produced by the test.
+    # This is the value passed to the `#expect` call.
     getter actual
 
+    # Creates the expectation partial.
     protected def initialize(label : String, @actual : ActualType)
       super(label)
     end
 
+    # Asserts that the `#actual` value matches some criteria.
+    # The criteria is defined by the matcher passed to this method.
     def to(matcher : Matchers::ValueMatcher(ExpectedType)) : Nil forall ExpectedType
       expectation = ValueExpectation.new(self, matcher)
       result = expectation.eval
       ExpectationRegistry.current.report(result)
     end
 
+    # Asserts that the `#actual` value *does not* match some criteria.
+    # This is effectively the opposite of `#to`.
     def to_not(matcher : Matchers::ValueMatcher(ExpectedType)) : Nil forall ExpectedType
       expectation = ValueExpectation.new(self, matcher)
       result = expectation.eval(true)

src/spectator/matchers/equality_matcher.cr

@@ -1,15 +1,23 @@
 require "./value_matcher"
 
 module Spectator::Matchers
+  # Common matcher that tests whether two values equal each other.
+  # The values are compared with the `==` operator.
   struct EqualityMatcher(ExpectedType) < ValueMatcher(ExpectedType)
+    # Determines whether the matcher is satisfied with the value given to it.
+    # True is returned if the match was successful, false otherwise.
     def match?(partial : Expectations::ValueExpectationPartial(ActualType)) : Bool forall ActualType
       partial.actual == expected
     end
 
+    # Describes the condition that satisfies the matcher.
+    # This is informational and displayed to the end-user.
     def message(partial : Expectations::ValueExpectationPartial(ActualType)) : String forall ActualType
       "Expected #{partial.label} to equal #{label} (using ==)"
     end
 
+    # Describes the condition that won't satsify the matcher.
+    # This is informational and displayed to the end-user.
     def negated_message(partial : Expectations::ValueExpectationPartial(ActualType)) : String forall ActualType
       "Expected #{partial.label} to not equal #{label} (using ==)"
     end

src/spectator/matchers/matcher.cr

@@ -1,7 +1,14 @@
 module Spectator::Matchers
+  # Common base class for all expectation conditions.
+  # A matcher looks at something produced by the SUT
+  # and evaluates whether it is correct or not.
   abstract struct Matcher
+    # Textual representation of what the matcher expects.
+    # This shouldn't be used in the conditional logic,
+    # but for verbose output to help the end-user.
     private getter label : String
 
+    # Creates the base of the matcher.
     private def initialize(@label)
     end
   end

src/spectator/matchers/value_matcher.cr

@@ -1,17 +1,32 @@
 require "./matcher"
 
 module Spectator::Matchers
+  # Category of matcher that uses a value.
+  # Matchers of this type expect that a SUT applies to the value in some way.
+  # Sub-types must implement `#match`, `#message`, and `#negated_message`.
+  # Those methods accept a `ValueExpectationPartial` to work with.
   abstract struct ValueMatcher(ExpectedType) < Matcher
+    # Expected value.
+    # Sub-types may use this value to test the expectation and generate message strings.
     private getter expected
 
+    # Creates the value matcher.
+    # The label should be a string representation of the expectation.
+    # The expected value is stored for later use.
     def initialize(label : String, @expected : ExpectedType)
       super(label)
     end
 
+    # Determines whether the matcher is satisfied with the value given to it.
+    # True is returned if the match was successful, false otherwise.
     abstract def match?(partial : ValueExpectationPartial(ActualType)) : Bool forall ActualType
 
+    # Describes the condition that satisfies the matcher.
+    # This is informational and displayed to the end-user.
     abstract def message(partial : ValueExpectationPartial(ActualType)) : String forall ActualType
 
+    # Describes the condition that won't satsify the matcher.
+    # This is informational and displayed to the end-user.
     abstract def negated_message(partial : ValueExpectationPartial(ActualType)) : String forall ActualType
   end
 end