Converted comments in dir Cura/cura to rst style

Converted doxygen style comments to reStructuredText style in the files found in Cura/cura directory using the script dox_2_rst.py (provided in the Uranium repo). Comments were manually checked and changed if needed.

1 files changed, 77 insertions, 63 deletions

diff --git a/cura/BuildVolume.py b/cura/BuildVolume.py
index 36edd427f7..76316f5e43 100755
--- a/cura/BuildVolume.py
+++ b/cura/BuildVolume.py
@@ -44,8 +44,9 @@ catalog = i18nCatalog("cura")
 PRIME_CLEARANCE = 6.5
 
 
-##  Build volume is a special kind of node that is responsible for rendering the printable area & disallowed areas.
 class BuildVolume(SceneNode):
+    """Build volume is a special kind of node that is responsible for rendering the printable area & disallowed areas."""
+
     raftThicknessChanged = Signal()
 
     def __init__(self, application: "CuraApplication", parent: Optional[SceneNode] = None) -> None:
@@ -113,7 +114,7 @@ class BuildVolume(SceneNode):
         self._has_errors = False
         self._application.getController().getScene().sceneChanged.connect(self._onSceneChanged)
 
-        #Objects loaded at the moment. We are connected to the property changed events of these objects.
+        # Objects loaded at the moment. We are connected to the property changed events of these objects.
         self._scene_objects = set()  # type: Set[SceneNode]
 
         self._scene_change_timer = QTimer()
@@ -163,10 +164,12 @@ class BuildVolume(SceneNode):
             self._scene_objects = new_scene_objects
             self._onSettingPropertyChanged("print_sequence", "value")  # Create fake event, so right settings are triggered.
 
-    ##  Updates the listeners that listen for changes in per-mesh stacks.
-    #
-    #   \param node The node for which the decorators changed.
     def _updateNodeListeners(self, node: SceneNode):
+        """Updates the listeners that listen for changes in per-mesh stacks.
+        
+        :param node: The node for which the decorators changed.
+        """
+
         per_mesh_stack = node.callDecoration("getStack")
         if per_mesh_stack:
             per_mesh_stack.propertyChanged.connect(self._onSettingPropertyChanged)
@@ -187,10 +190,14 @@ class BuildVolume(SceneNode):
         if shape:
             self._shape = shape
 
-    ##  Get the length of the 3D diagonal through the build volume.
-    #
-    #   This gives a sense of the scale of the build volume in general.
     def getDiagonalSize(self) -> float:
+        """Get the length of the 3D diagonal through the build volume.
+
+        This gives a sense of the scale of the build volume in general.
+
+        :return: length of the 3D diagonal through the build volume
+        """
+
         return math.sqrt(self._width * self._width + self._height * self._height + self._depth * self._depth)
 
     def getDisallowedAreas(self) -> List[Polygon]:
@@ -226,9 +233,9 @@ class BuildVolume(SceneNode):
 
         return True
 
-    ##  For every sliceable node, update node._outside_buildarea
-    #
     def updateNodeBoundaryCheck(self):
+        """For every sliceable node, update node._outside_buildarea"""
+
         if not self._global_container_stack:
             return
 
@@ -295,8 +302,13 @@ class BuildVolume(SceneNode):
             for child_node in children:
                 child_node.setOutsideBuildArea(group_node.isOutsideBuildArea())
 
-    ##  Update the outsideBuildArea of a single node, given bounds or current build volume
     def checkBoundsAndUpdate(self, node: CuraSceneNode, bounds: Optional[AxisAlignedBox] = None) -> None:
+        """Update the outsideBuildArea of a single node, given bounds or current build volume
+
+        :param node: single node
+        :param bounds: bounds or current build volume
+        """
+
         if not isinstance(node, CuraSceneNode) or self._global_container_stack is None:
             return
 
@@ -484,8 +496,9 @@ class BuildVolume(SceneNode):
             self._disallowed_area_size = max(size, self._disallowed_area_size)
         return mb.build()
 
-    ##  Recalculates the build volume & disallowed areas.
     def rebuild(self) -> None:
+        """Recalculates the build volume & disallowed areas."""
+
         if not self._width or not self._height or not self._depth:
             return
 
@@ -586,8 +599,9 @@ class BuildVolume(SceneNode):
     def _onStackChanged(self):
         self._stack_change_timer.start()
 
-    ##  Update the build volume visualization
     def _onStackChangeTimerFinished(self) -> None:
+        """Update the build volume visualization"""
+
         if self._global_container_stack:
             self._global_container_stack.propertyChanged.disconnect(self._onSettingPropertyChanged)
             extruders = ExtruderManager.getInstance().getActiveExtruderStacks()
@@ -712,15 +726,15 @@ class BuildVolume(SceneNode):
         self._depth = self._global_container_stack.getProperty("machine_depth", "value")
         self._shape = self._global_container_stack.getProperty("machine_shape", "value")
 
-    ##  Calls _updateDisallowedAreas and makes sure the changes appear in the
-    #   scene.
-    #
-    #   This is required for a signal to trigger the update in one go. The
-    #   ``_updateDisallowedAreas`` method itself shouldn't call ``rebuild``,
-    #   since there may be other changes before it needs to be rebuilt, which
-    #   would hit performance.
-
     def _updateDisallowedAreasAndRebuild(self):
+        """Calls :py:meth:`cura.BuildVolume._updateDisallowedAreas` and makes sure the changes appear in the scene.
+        
+        This is required for a signal to trigger the update in one go. The
+        :py:meth:`cura.BuildVolume._updateDisallowedAreas` method itself shouldn't call
+        :py:meth:`cura.BuildVolume.rebuild`, since there may be other changes before it needs to be rebuilt,
+        which would hit performance.
+        """
+
         self._updateDisallowedAreas()
         self._updateRaftThickness()
         self._extra_z_clearance = self._calculateExtraZClearance(ExtruderManager.getInstance().getUsedExtruderStacks())
@@ -782,15 +796,14 @@ class BuildVolume(SceneNode):
         for extruder_id in result_areas_no_brim:
             self._disallowed_areas_no_brim.extend(result_areas_no_brim[extruder_id])
 
-    ##  Computes the disallowed areas for objects that are printed with print
-    #   features.
-    #
-    #   This means that the brim, travel avoidance and such will be applied to
-    #   these features.
-    #
-    #   \return A dictionary with for each used extruder ID the disallowed areas
-    #   where that extruder may not print.
     def _computeDisallowedAreasPrinted(self, used_extruders):
+        """Computes the disallowed areas for objects that are printed with print features.
+        
+        This means that the brim, travel avoidance and such will be applied to these features.
+        
+        :return: A dictionary with for each used extruder ID the disallowed areas where that extruder may not print.
+        """
+
         result = {}
         adhesion_extruder = None #type: ExtruderStack
         for extruder in used_extruders:
@@ -828,18 +841,18 @@ class BuildVolume(SceneNode):
 
         return result
 
-    ##  Computes the disallowed areas for the prime blobs.
-    #
-    #   These are special because they are not subject to things like brim or
-    #   travel avoidance. They do get a dilute with the border size though
-    #   because they may not intersect with brims and such of other objects.
-    #
-    #   \param border_size The size with which to offset the disallowed areas
-    #   due to skirt, brim, travel avoid distance, etc.
-    #   \param used_extruders The extruder stacks to generate disallowed areas
-    #   for.
-    #   \return A dictionary with for each used extruder ID the prime areas.
     def _computeDisallowedAreasPrimeBlob(self, border_size: float, used_extruders: List["ExtruderStack"]) -> Dict[str, List[Polygon]]:
+        """Computes the disallowed areas for the prime blobs.
+        
+        These are special because they are not subject to things like brim or travel avoidance. They do get a dilute
+        with the border size though because they may not intersect with brims and such of other objects.
+        
+        :param border_size: The size with which to offset the disallowed areas due to skirt, brim, travel avoid distance
+         , etc.
+        :param used_extruders: The extruder stacks to generate disallowed areas for.
+        :return: A dictionary with for each used extruder ID the prime areas.
+        """
+
         result = {}  # type: Dict[str, List[Polygon]]
         if not self._global_container_stack:
             return result
@@ -867,19 +880,18 @@ class BuildVolume(SceneNode):
 
         return result
 
-    ##  Computes the disallowed areas that are statically placed in the machine.
-    #
-    #   It computes different disallowed areas depending on the offset of the
-    #   extruder. The resulting dictionary will therefore have an entry for each
-    #   extruder that is used.
-    #
-    #   \param border_size The size with which to offset the disallowed areas
-    #   due to skirt, brim, travel avoid distance, etc.
-    #   \param used_extruders The extruder stacks to generate disallowed areas
-    #   for.
-    #   \return A dictionary with for each used extruder ID the disallowed areas
-    #   where that extruder may not print.
     def _computeDisallowedAreasStatic(self, border_size:float, used_extruders: List["ExtruderStack"]) -> Dict[str, List[Polygon]]:
+        """Computes the disallowed areas that are statically placed in the machine.
+        
+        It computes different disallowed areas depending on the offset of the extruder. The resulting dictionary will
+         therefore have an entry for each extruder that is used.
+        
+        :param border_size: The size with which to offset the disallowed areas due to skirt, brim, travel avoid distance
+         , etc.
+        :param used_extruders: The extruder stacks to generate disallowed areas for.
+        :return: A dictionary with for each used extruder ID the disallowed areas where that extruder may not print.
+        """
+
         # Convert disallowed areas to polygons and dilate them.
         machine_disallowed_polygons = []
         if self._global_container_stack is None:
@@ -1010,13 +1022,14 @@ class BuildVolume(SceneNode):
 
         return result
 
-    ##  Private convenience function to get a setting from every extruder.
-    #
-    #   For single extrusion machines, this gets the setting from the global
-    #   stack.
-    #
-    #   \return A sequence of setting values, one for each extruder.
     def _getSettingFromAllExtruders(self, setting_key: str) -> List[Any]:
+        """Private convenience function to get a setting from every extruder.
+        
+        For single extrusion machines, this gets the setting from the global stack.
+        
+        :return: A sequence of setting values, one for each extruder.
+        """
+
         all_values = ExtruderManager.getInstance().getAllExtruderSettings(setting_key, "value")
         all_types = ExtruderManager.getInstance().getAllExtruderSettings(setting_key, "type")
         for i, (setting_value, setting_type) in enumerate(zip(all_values, all_types)):
@@ -1101,12 +1114,13 @@ class BuildVolume(SceneNode):
 
         return move_from_wall_radius
 
-    ##  Calculate the disallowed radius around the edge.
-    #
-    #   This disallowed radius is to allow for space around the models that is
-    #   not part of the collision radius, such as bed adhesion (skirt/brim/raft)
-    #   and travel avoid distance.
     def getEdgeDisallowedSize(self):
+        """Calculate the disallowed radius around the edge.
+        
+        This disallowed radius is to allow for space around the models that is not part of the collision radius, such as
+         bed adhesion (skirt/brim/raft) and travel avoid distance.
+        """
+
         if not self._global_container_stack or not self._global_container_stack.extruderList:
             return 0