Code docs for MethodStep

lib/piece_pipe/method_step.rb

@@ -1,4 +1,25 @@
 module PiecePipe
+  # MethodStep makes it possible to define a pipeline step by wrapping a Method
+  # object. Eg,
+  #   PiecePipe::Pipeline.new.step( method(:do_something) )
+  #
+  # In this contrived example, whatever class is building the Pipeline has
+  # a #do_something method, which is accessed as a Method object from Ruby's
+  # reflection API via Kernel#method.
+  #
+  # If the wrapped method accepts a single parameter (arity 1), the inputs
+  # to your MethodStep will be passed in via this parameter, and the return
+  # value of your method will be automatically #produced, even if you 
+  # return nil.
+  #
+  # If the wrapped method accepts TWO parameters (arity 2), the inputs will
+  # still arrive via the first paramter, and the second parameter will
+  # be a "producer" object that responds to #produce.  This gives you the
+  # flexibility to #produce zero-or-many items, as in normal Step 
+  # subclasses.  In the case of arity-2 methods, the return value
+  # is disregarded.  Failing to call producer#produce will result
+  # in a filtering-out of objects.
+  #
   class MethodStep < Step
     def initialize(meth)
       raise "method cannot be nil" if meth.nil?