 
 #
 # mock() is a shorthand function to ensure that .check() is called 
-# on mock objects.  For example, using Mock directly:
-#
-#   describe "Something", ->
-#     it "does something", ->
-#       my_mock = new Mock()            # Create a mock object.
-#       my_mock.expects("my_method")    # The mock should expect my_method to be invoked.
-#       ...                             # Do something that is supposed to invoke my_method.
-#       my_mock.check()                 # Need to remember to check that my_method was invoked.
-#
-#     it "does something else", ->
-#       ...
-#
-# Using the mock() function:
-#
-#   describe "Something", ->
-#     it "does something", ->
-#       mock (my_mock) ->               # my_mock is created automatically.
-#         my_mock.expects("my_method")  # The mock should expect my_method to be invoked.
-#         ...                           # Do something that is supposed to invoke my_method.
-#                                       # .check() is called automatically here by mock().
-#
-#     it "does something else", ->
-#       ...
-#
-# The mock() function provides up to five mock objects:
-#
-#   mock (m1, m2, m3, m4, m5) ->
-#     m1.expects("method1")
-#     m2.expects("method2")
-#     ...
+# on mock objects.  As such, it takes a function (the test code)
+# argument, creates five mock objects, invokes the function with
+# the five mocks, and then calls check() on the mocks.
 #
 mock = (fn) ->
   mocks = ( new Mock() for i in [1..5] )

    @
    
  #
  # my_mock = (new Mock).expects("my_method")
  # my_mock.my_method()
  # my_mock.check()
  #
  check: ->
    @_check_for_uncalled_signatures()

#
# MethodSignature is an internal data structure that represents 
# a mocked method.  Stores the method name, the expected arguments,
# the value to return, and whether it has actually been called.
# For example, the following:
#
#   my_mock = (new Mock).expects("my_method").args(1,2,3).returns(42)
#
