Add docs for allow and receive

src/spectator/dsl/mocks.cr

@@ -128,10 +128,45 @@ module Spectator::DSL
       ::Spectator::LazyDouble.new({{**value_methods}})
     end
 
-    macro allow(stubbable)
+    # Targets a stubbable object (such as a mock or double) for operations.
-      ::Spectator::Allow.new({{stubbable}})
+    #
+    # The *stubbable* must be a `Stubbable`.
+    # This method is expected to be followed up with `.to receive()`.
+    #
+    # ```
+    # dbl = dbl(:foobar)
+    # allow(dbl).to receive(:foo).and_return(42)
+    # ```
+    def allow(stubbable : Stubbable)
+      ::Spectator::Allow.new(stubbable)
     end
 
+    # Helper method producing a compilation error when attempting to stub a non-stubbable object.
+    #
+    # Triggered in cases like this:
+    # ```
+    # allow(42).to receive(:to_s).and_return("123")
+    # ```
+    def allow(stubbable)
+      {% raise "Target of `allow()` must be stubbable (mock or double)." %}
+    end
+
+    # Begins the creation of a stub.
+    #
+    # The *method* is the name of the method being stubbed.
+    # It should not define any parameters, it should be just the method name as a literal symbol or string.
+    #
+    # Alone, this method returns a `NullStub`, which allows a stubbable object to return nil from a method.
+    # This macro is typically followed up with a method like `and_return` to change the stub's behavior.
+    #
+    # ```
+    # dbl = dbl(:foobar)
+    # allow(dbl).to receive(:foo)
+    # expect(dbl.foo).to be_nil
+    #
+    # allow(dbl).to receive(:foo).and_return(42)
+    # expect(dbl.foo).to eq(42)
+    # ```
     macro receive(method)
       ::Spectator::NullStub.new({{method.id.symbolize}})
     end

src/spectator/mocks/allow.cr

@@ -2,11 +2,22 @@ require "./stub"
 require "./stubbable"
 
 module Spectator
+  # Targets a stubbable object.
+  #
+  # This type is effectively part of the mock DSL.
+  # It is primarily used in the mock DSL to provide this syntax:
+  # ```
+  # allow(dbl).to
+  # ```
   struct Allow(T)
+    # Creates the stub target.
+    #
+    # The *target* must be a kind of `Stubbable`.
     def initialize(@target : T)
       {% raise "Target of `allow` must be stubbable (a mock or double)." unless T < Stubbable %}
     end
 
+    # Applies a stub to the targeted stubbable object.
     def to(stub : Stub) : Nil
       @target._spectator_define_stub(stub)
     end