errors.rb in eco-helpers-1.0.14

- old
+ new

@@ -1,45 +1,59 @@
 module Eco
   module API
     class Session
       class Batch
+        # Helper object linked to a `batch status`
         class Errors
 
+          # @attr_reader status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           attr_reader :status
 
+          # @param status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           def initialize(status:)
-            "Expected Batch::Status as root. Given: #{status.class}" unless status.is_a?(Batch::Status)
+            "Expected Batch::Status as root. Given: #{status.class}" unless status.is_a?(Eco::API::Session::Batch::Status)
             @status = status
           end
 
+          # @see [Eco::API::Session::Batch::Status#queue]
           def queue
             status.queue
           end
 
+          # @see [Eco::API::Session::Batch::Status#method]
           def method
             status.method
           end
 
+          # @see [Eco::API::Session::Batch::Status#to_index]
           def to_index(*args)
             status.to_index(*args)
           end
 
+          # @return [Eco::API::Session] currently active `session`
           def session
             status.session
           end
 
           def logger
             status.logger
           end
 
+          # Was there any **error** as a result of this batch?
+          # @return [Boolean] `true` if any of the queried _entries_ got an unsuccessful `Ecoportal::API::Common::BatchResponse`
           def any?
             queue.any? {|query| !status[query].success?}
           end
 
+          # Input entries that got launched against the server.
+          # @raise [Exception] if there are elements of the final `queue` that did not get response
+          # @note discards those that did not get _response_ from the Server (so those that were not queried)
+          #   - please, observe that this can only happen if there were repeated entries in the `source_queue`
+          # @return [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]
           def entries
             queue.each_with_index.map do |query, i|
-              unless status[i]
+              unless response = status[i]
                 msg  = "Error: query with no response. You might have duplicated entries in your queue.\n"
                 msg += "Queue length: #{queue.length}; Queue elements class: #{queue.first.class}\n"
                 msg += "Query with no response. Person: #{person_ref(query)}\n"
                 queue.map do |entry|
                   if [:id, :external_id, :email].any? {|attr| (v = get_attr(entry, attr)) && v == get_attr(query, attr)}
@@ -47,10 +61,10 @@
                   end
                 end
                 raise msg
               end
 
-              status[i].success? ? nil : query
+              response.success? ? nil : query
             end.compact
           end
 
           def errors
             entries.each_with_object([]) do |entry, arr|