add documentation

xtreemfs_client/physicalPlacementRealizer.py

@@ -74,9 +74,22 @@ class PhysicalPlacementRealizer(object):
         return files_to_be_moved_list
 
     def update_files_to_be_moved(self):
+        """
+        update self.files_to_be_moved: check for all elements whether they still need to be moved.
+        right now, we simply recalculate it from scratch, yielding the correct result, but being inefficient.
+        :return:
+        """
+        # TODO implement
         self.calculate_files_to_be_moved()
 
     def calculate_files_to_be_moved(self):
+        """
+        method to populate self.files_to_be_moved.
+        for each file in self.osd_manager.managed_folder, it is checked whether the file is on the OSD assigned by
+        self.osd_manager.distribution. if this is not the case, the file is added to self.files_to_be_moved.
+        more precisely, it is appended to the list at key (origin_osd, target_osd) in self.files_to_be_moved.
+        :return:
+        """
         self.files_to_be_moved = {}
         managed_folders = self.osd_manager.get_depth_2_subdirectories()
         for managed_folder in managed_folders:
@@ -127,6 +140,12 @@ class PhysicalPlacementRealizer(object):
                         self.files_to_be_moved[movement_key].append(file_to_move)
 
     def move_files_randomly(self):
+        """
+        executes the necessary commands in order to move all files in self.files_to_be_moved to their target OSD.
+        at most self.max_total_files_in_progress are treated in the same time.
+        files are processed in random order.
+        :return:
+        """
         files_to_be_moved = self.get_list_of_all_files_to_be_moved()
 
         if self.debug:
@@ -160,7 +179,17 @@ class PhysicalPlacementRealizer(object):
 
     def execute_command_list(self, change_policy_command_list, create_replica_command_list,
                              delete_replica_command_list):
-
+        """
+        executes three list of commands, that are typically needed for moving files in XtreemFS from their current OSD
+        to the designated target OSD. the lists are treated as their order in the argument list. commands from the next
+        list are only executed when all commands of the previous list have returned (or been killed).
+        deletion commands are repeated a number of times, as the target OSD requires some time to create the new replica
+        (for fetching all objects, i.e., file content).
+        :param change_policy_command_list: list of change replication policy commands to be executed.
+        :param create_replica_command_list: list of create replica commands to be executed.
+        :param delete_replica_command_list: list of delete replica commands to be executed.
+        :return:
+        """
         start_time = time.time()
         if self.debug:
             print("starting execution of " + str(len(change_policy_command_list)) + " change policy commands...")