lib/substation/response.rb in substation-0.0.3 vs lib/substation/response.rb in substation-0.0.4

@@ -1,41 +1,67 @@
 module Substation
 
   # Base class for action responses
   #
+  # The following code illustrates context and serves as setup for all
+  # instance method doc examples
+  #
+  #   module App
+  #     class Environment
+  #       def initialize(storage, logger)
+  #         @storage, @logger = storage, logger
+  #       end
+  #     end
+  #
+  #     class SuccessfulAction
+  #       def self.call(request)
+  #         data = perform_work
+  #         request.success(data)
+  #       end
+  #     end
+  #
+  #     class FailingAction
+  #       def self.call(request)
+  #         error = perform_work
+  #         request.error(error)
+  #       end
+  #     end
+  #   end
+  #
+  #   storage    = SomeStorageAbstraction.new
+  #   env        = App::Environment.new(storage, Logger.new($stdout))
+  #   dispatcher = Substation::Dispatcher.coerce({
+  #     :successful_action => { :action => App::SuccessfulAction },
+  #     :failing_action    => { :action => App::FailingAction }
+  #   }, env)
+  #
   # @abstract
   class Response
 
     include AbstractType
     include Equalizer.new(:request, :output)
     include Adamantium::Flat
 
-    # The environment used to return this response
+    # The application environment used within an action
     #
-    # @return [Environment]
+    # @example
     #
-    # @api private
+    #   response = dispatcher.call(:successful_action, :some_input)
+    #   response.env # => env passed to Substation::Dispatcher.coerce(config, env)
+    #
+    # @return [Object]
+    #
+    # @api public
     attr_reader :env
 
     # The request model instance passed into an action
     #
     # @example
     #
-    #   class SomeUseCase
-    #     def self.call(request)
-    #       data = perform_work
-    #       request.success(data)
-    #     end
-    #   end
+    #   response = dispatcher.call(:successful_action, :some_input)
+    #   response.input # => :some_input
     #
-    #   env = Substation::Environment.coerce({
-    #     'some_use_case' => { 'action' => 'SomeUseCase' }
-    #   })
-    #
-    #   response = env.dispatch(:some_use_case, :input)
-    #   response.input # => :input
-    #
     # @see Request#input
     #
     # @return [Object]
     #
     # @api public
@@ -43,23 +69,13 @@
 
     # The data wrapped inside an action {Response}
     #
     # @example
     #
-    #   class SomeUseCase
-    #     def self.call(request)
-    #       request.success(:output)
-    #     end
-    #   end
+    #   response = dispatcher.call(:successful_action, :some_input)
+    #   response.output # => data passed to request.success(data)
     #
-    #   env = Substation::Environment.coerce({
-    #     'some_use_case' => { 'action' => 'SomeUseCase' }
-    #   })
-    #
-    #   response = env.dispatch(:some_use_case, :input)
-    #   response.output # => :output
-    #
     # @return [Object]
     #
     # @api public
     attr_reader :output
 
@@ -88,22 +104,11 @@
     # @see Success#success?
     # @see Failure#success?
     #
     # @example
     #
-    #   class SomeUseCase
-    #     def self.call(request)
-    #       request.success(:data)
-    #     end
-    #   end
-    #
-    #   env = Substation::Environment.coerce({
-    #     'some_use_case' => { 'action' => 'SomeUseCase' }
-    #   })
-    #
-    #   response = env.dispatch(:some_use_case, :input)
-    #   response.class    # Substation::Response::Success
+    #   response = dispatcher.call(:successful_action, :some_input)
     #   response.success? # => true
     #
     # @return [Boolean]
     #   true if successful, false otherwise
     #
@@ -124,21 +129,11 @@
 
       # Tests wether this response was successful
       #
       # @example
       #
-      #   class SomeUseCase
-      #     def self.call(request)
-      #       request.error(:output)
-      #     end
-      #   end
-      #
-      #   env = Substation::Environment.coerce({
-      #     'some_use_case' => { 'action' => 'SomeUseCase' }
-      #   })
-      #
-      #   response = env.dispatch(:some_use_case, :input)
+      #   response = dispatcher.call(:failing_action, :some_input)
       #   response.success? # => false
       #
       # @return [false]
       #
       # @api public
@@ -152,20 +147,10 @@
 
       # Tests wether this response was successful
       #
       # @example
       #
-      #   class SomeUseCase
-      #     def self.call(request)
-      #       request.success(:data)
-      #     end
-      #   end
-      #
-      #   env = Substation::Environment.coerce({
-      #     'some_use_case' => { 'action' => 'SomeUseCase' }
-      #   })
-      #
-      #   response = env.dispatch(:some_use_case, :input)
+      #   response = dispatcher.call(:successful_action, :some_input)
       #   response.success? # => true
       #
       # @return [true]
       #
       # @api public