jobs.rb in eco-helpers-1.5.8

- old
+ new
@@ -40,34 +40,53 @@
 
           def exists?(name)
             @jobs.key?(name)
           end
 
+          # It retrieves an existing job named `name` or creates it if it doesn't exist.
+          # @note
+          #   - the block should only be passed when creating the job
+          # @param [see @Eco::API::Session::Batch::Jobs#new]
+          # @return [Eco::API::Session::Batch::Job]
           def job(name, type: nil, sets: nil, usecase: nil, &block)
+            fatal "Can't give a job post-launch callback &block to an already existing job" if exists?(name)
             new(name, type: type, sets: sets, usecase: usecase, &block) unless exists?(name)
-            self[name].tap do |job|
-              block.call(job) if block
-            end
+            self[name]
           end
 
+          # Creates a new `Batch::Job` included as part of this `Batch::Jobs`.
+          # @param [see Eco::API::Session::Job#new]
+          # @yield [job, status] callback after launching the batch job request against the server.
+          # @yieldparam job [Eco::API::Session::Batch::Job] the job we have launched against the server.
+          # @yieldparam status [Eco::API::Session::Batch::Status] the status of the batch job launch.
+          # @return [Eco::API::Session::Batch::Job]
           def new(name, type:, sets:, usecase: nil, &block)
             fatal "Can't create job named '#{name}' because it already exists." if exists?(name)
 
             Batch::Job.new(enviro, name: name, type: type, sets: sets, usecase: usecase).tap do |job|
               add(job, &block)
             end
           end
 
+          # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` to add.
+          # @yield [job, status] callback after launching the batch job request against the server.
+          # @yieldparam job [Eco::API::Session::Batch::Job] the job we have launched against the server.
+          # @yieldparam status [Eco::API::Session::Batch::Status] the status of the batch job launch.
+          # @return [Eco::API::Session::Batch::Job]
           def add(job)
             fatal "Expected Eco::API::Session::Batch::Job object. Given #{job.class}" unless job.is_a?(Eco::API::Session::Batch::Job)
             @jobs[job.name] = job
             @callbacks[job] = Proc.new if block_given?
           end
 
           def pending?
             any? {|job| job.pending?}
           end
 
+          # Launches every `Batch::Job` in the group.
+          # @note
+          #   - if there was post-launch callback for a `Batch::Job`, it calls it.
+          # @return [Hash<Eco::API::Session::Batch::Job, Eco::API::Session::Batch::Status>]
           def launch(simulate: false)
             each do |job|
               if job.pending?
                 status[job] = job_status = job.launch(simulate: simulate)
                 callback    = @callbacks[job]