Improve code documentation

service/lib/dinstaller/dbus/interfaces/dasd.rb

@@ -126,6 +126,16 @@ def dasd_format(paths)
           dasds = find_dasds(paths)
           return [1, "/"] if dasds.nil?
 
+          # Theoreticaly, there is room for a race condition here if the callbacks 'progress' or
+          # 'finish' are called before the job is created below. But in practice it will not happen
+          # because dasd_backend#format sleeps before calling any of the callbacks and, of course,
+          # it only calls them if the formatting process effectively started.
+          #
+          # We can change the approach in the future and always create the job beforehand if we feel
+          # the risk is not acceptable. That would make the Format operation a bit less consistent
+          # with other methods in this interface. If the format process cannot be started it would
+          # still return 0 as result and would create a job in the tree with kind of meaningless
+          # progress information representing the failed execution.
           job = nil
           progress = proc { |statuses| job.update_format(statuses) }
           finish = proc { |result| job.finish_format(result) }

service/lib/dinstaller/storage/dasd/format_operation.rb

@@ -31,6 +31,9 @@ class FormatOperation
         # Constructor
         #
         # @param dasds [Array<Y2S390:Dasd>] devices to format
+        # @param on_progress [Array<Proc>] callbacks to be called when the status of the operation
+        #   is refreshed
+        # @param on_finish [Array<Proc>] callbacks to be called when the operation ends
         def initialize(dasds, on_progress = [], on_finish = [])
           @process = Y2S390::FormatProcess.new(dasds)
           @on_progress = on_progress
@@ -50,7 +53,9 @@ def run
 
           process.initialize_summary
           Thread.new do
-            wait # Ensure we finish first
+            # Just to be absolutely sure, sleep to ensure the #run method returns and its result is
+            # processed by the caller before we start calling callbacks
+            wait
             monitor_process
           end
           process.summary.values